@chidchanun/bcp 0.1.20 → 0.1.21

package/README.md

@@ -1,8 +1,8 @@
 # BCP Framework
 
-BCP Framework is a React full-stack framework with file-based routing, SSR, client navigation, API routes, middleware, metadata, client islands, cache/revalidation, security defaults and standalone production builds.
+BCP Framework is a React full-stack framework with file-based routing, SSR, client navigation, API routes, middleware, metadata, client islands, cache/revalidation, validation, structured errors, authentication, database primitives, security defaults and standalone production builds.
 
-> Current release target: `0.1.11`. BCP is still pre-1.0 and validates each release candidate before the manual npm publish step.
+> Current release target: `0.1.21`. BCP is still pre-1.0 and validates each release candidate before the manual npm publish step.
 
 ## Quick start
 
@@ -86,6 +86,30 @@ See [Application Modules](docs/application-modules.md) for the complete boundary
 
 Generated Tailwind projects compile to `public/bcp.css`. BCP 0.1.6 inlines that stylesheet into SSR HTML when it is 8 KiB or smaller, removing the stylesheet request from the initial render-critical path. Larger stylesheets remain external so the browser can cache them normally. If the application's Content Security Policy does not allow inline styles, BCP automatically keeps the external stylesheet link.
 
+## Development hydration parity
+
+BCP 0.1.21 fixes a development-only hydration mismatch where the SSR transform and the React Refresh client transform could assign different semantic values to the same multiline JSX attribute.
+
+For example, this is supported application code:
+
+```tsx
+<div
+    className="
+        min-h-screen
+        bg-white
+        text-slate-950
+    "
+/>
+```
+
+BCP 0.1.20 already normalized Windows `CRLF` and standalone `CR` source line endings to `LF`, but Babel's JSX transform could still collapse the multiline quoted attribute to a single-space-separated string while SSR preserved the original line breaks and indentation.
+
+In 0.1.21, Babel remains responsible for TypeScript stripping and React Refresh registration, but JSX is preserved until esbuild compiles it with the development JSX runtime. This keeps static JSX attribute semantics aligned between SSR and the development client bundle.
+
+Applications should not need to rewrite multiline classes to one line or use `suppressHydrationWarning` to work around framework transform differences. Genuine runtime mismatches caused by values such as `Date.now()`, `Math.random()`, browser-only initial state, locale differences or changing external data still need to be fixed in application code.
+
+See [Hydration and deterministic rendering](docs/hydration.md) for the transform pipeline and troubleshooting guidance.
+
 ## Commands
 
 ```bash
@@ -117,7 +141,7 @@ bcp update --dry-run
 Or select a published version/dist-tag explicitly:
 
 ```bash
-bcp update 0.1.11
+bcp update 0.1.21
 bcp update next
 ```
 
@@ -777,12 +801,19 @@ No real npm publish command is run automatically by the repository.
 - [Server Data Loaders](docs/server-data-loaders.md)
 - [Protected Route Guards](docs/route-guards.md)
 - [Form Actions and Server Mutations](docs/form-actions.md)
+- [Validation](docs/validation.md)
+- [Error Handling](docs/error-handling.md)
+- [Authentication](docs/authentication.md)
+- [Auth Route Guards](docs/auth-route-guards.md)
 - [JWT Cookie Sessions](docs/session-auth.md)
+- [Database](docs/database.md)
+- [Database Migrations](docs/database-migrations.md)
+- [Middleware](docs/middleware.md)
+- [Hydration and deterministic rendering](docs/hydration.md)
 - [Updating BCP Framework](docs/updating.md)
 - [Routing](docs/routing.md)
 - [Configuration](docs/configuration.md)
 - [Caching](docs/caching.md)
-- [Middleware](docs/middleware.md)
 - [Security](docs/security.md)
 - [Deployment](docs/deployment.md)
 - [Releasing](docs/releasing.md)

package/docs/README.md

@@ -4,7 +4,7 @@ This directory is the documentation source of truth for the BCP Framework docume
 
 The recommended documentation website project name is `bcp-docs`.
 
-> Documentation target: BCP Framework `0.1.20`
+> Documentation target: BCP Framework `0.1.21`
 
 ## Purpose
 
@@ -63,7 +63,7 @@ The website should not invent API behavior that is not documented or tested in t
 | Website route | Source file | Description |
 | --- | --- | --- |
 | `/docs/middleware` | `middleware.md` | Middleware System v2 and v1 compatibility |
-| `/docs/hydration` | `hydration.md` | SSR/client hydration, deterministic rendering and Windows CRLF behavior |
+| `/docs/hydration` | `hydration.md` | SSR/client transform parity, deterministic rendering and Windows line endings |
 | `/docs/caching` | `caching.md` | Cache and revalidation |
 | `/docs/security` | `security.md` | Framework security defaults |
 | `/docs/development-logging` | `development-logging.md` | Development request logging |
@@ -75,9 +75,9 @@ Use the files under `docs/releases/` for release pages.
 Recommended route format:
 
 ```text
-/releases/0.1.18
 /releases/0.1.19
 /releases/0.1.20
+/releases/0.1.21
 ```
 
 The newest release should also be available from `/releases`.
@@ -97,7 +97,8 @@ Recommended feature groups:
 - Loading and error UI
 - API routes
 - Client islands / partial hydration
-- Deterministic development hydration across LF/CRLF source checkouts
+- Deterministic development hydration across server/client transform pipelines
+- LF/CRLF-safe development source handling
 
 ### Server data and mutations
 
@@ -217,9 +218,9 @@ Production
   Development Logging
 
 Releases
+  0.1.21
   0.1.20
   0.1.19
-  0.1.18
 ```
 
 ## Suggested documentation page layout
@@ -351,7 +352,7 @@ See `validation.md` for the complete API and examples.
 
 ## Error Handling documentation priority
 
-BCP 0.1.20 introduces the public `bcp/error` entrypoint and a standard HTTP error envelope.
+BCP 0.1.20 introduced the public `bcp/error` entrypoint and a standard HTTP error envelope.
 
 The docs website should clearly distinguish:
 
@@ -375,17 +376,27 @@ See `error-handling.md` for the complete API and examples.
 
 ## Hydration documentation priority
 
-BCP 0.1.20 also fixes a Windows development hydration mismatch caused by CRLF source line endings passing through the React Refresh/Babel transform differently from SSR.
+BCP 0.1.20 added line-ending normalization for the development React Refresh path. That removed the Windows `CRLF` versus `LF` mismatch, but a second issue remained when Babel compiled multiline quoted JSX attributes and collapsed their whitespace differently from SSR.
+
+BCP 0.1.21 completes this fix by keeping Babel responsible for TypeScript removal and React Refresh instrumentation while leaving JSX untransformed. esbuild then performs the development JSX transform with the development JSX runtime enabled.
 
 The docs website should make these points clear:
 
-- multiline JSX attributes such as template-literal `className` values are supported,
-- developers should not need to rewrite them as one-line strings to avoid framework hydration warnings,
-- BCP normalizes `CRLF` and standalone `CR` source line endings to `LF` before the development Babel transform,
+- multiline quoted JSX attributes are supported,
+- multiline template-literal JSX expressions are supported,
+- developers should not need to rewrite multiline `className` values as one-line strings to avoid framework hydration warnings,
+- `CRLF` and standalone `CR` source line endings are normalized to `LF` before development instrumentation,
+- React Refresh instrumentation must not change the semantic value of JSX attributes,
 - the framework fix does not suppress genuine hydration mismatches caused by random values, locale differences, browser-only initial branches, changing external data or invalid HTML,
 - `suppressHydrationWarning` is not a general-purpose solution.
 
-See `hydration.md` for the full explanation and troubleshooting steps.
+See `hydration.md` for the full explanation, transform pipeline and troubleshooting steps.
+
+## Release roadmap adjustment
+
+`0.1.21` is reserved for the hydration parity hotfix because `0.1.20` was already published before the remaining Babel JSX whitespace mismatch was isolated.
+
+The previously planned Developer Tools release moves to `0.1.22`, and later roadmap items should shift forward accordingly unless they are regrouped into a larger milestone.
 
 ## Release workflow for documentation
 

package/docs/hydration.md

@@ -2,21 +2,21 @@
 
 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.
 
-## Windows CRLF support
+## Development transform parity
 
-BCP Framework 0.1.20 normalizes application source line endings before the development React Refresh/Babel transform.
+BCP Framework 0.1.21 fixes a development hydration mismatch caused by the server and client using different JSX transform semantics.
 
-This fixes a Windows-specific hydration warning that could appear when a JSX attribute used a multiline template literal, for example:
+A common trigger is a multiline quoted JSX attribute:
 
 ```tsx
 export default function Page() {
     return (
         <main
-            className={`
+            className="
                 min-h-screen
                 bg-white
                 text-slate-950
-            `}
+            "
         >
             Hello
         </main>
@@ -24,13 +24,63 @@ export default function Page() {
 }
 ```
 
-On a CRLF checkout, the development client transform could previously preserve carriage-return characters differently from the SSR transform. React then compared two visually equivalent class lists whose underlying strings were different and reported a hydration mismatch.
+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.
 
-BCP now normalizes both `CRLF` (`\r\n`) and standalone `CR` (`\r`) source line endings to `LF` (`\n`) before Babel processes development application modules. Developers do not need to rewrite multiline `className` values as one line to work around this 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 line-ending fix addresses deterministic source transformation. It does not hide genuine hydration differences caused by application behavior.
+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:
 
@@ -55,6 +105,7 @@ 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.
 
@@ -91,22 +142,49 @@ export default function BrowserValue() {
 }
 ```
 
-## Development and production
+## 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.
 
-The Windows CRLF issue was specific to the development React Refresh/Babel path. Production client compilation uses the production esbuild pipeline. The 0.1.20 fix makes development source handling deterministic before Babel so development hydration matches the SSR semantics.
+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 this fix:
+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. inspect the first differing server/client value in the React hydration warning,
-5. check for request-time, random, locale, browser-only or externally changing values.
+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 with a multiline JSX `className`. The development client bundle is required to normalize source line endings before the React Refresh Babel transform.
+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.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.20",
+  "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",

package/packages/bundler/src/index.ts

@@ -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 ใหม่
@@ -1737,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
@@ -1757,17 +1761,6 @@ function createReactRefreshPlugin(
                         ]);
                     }
 
-                    presets.push([
-                        presetReact,
-                        {
-                            runtime:
-                                "automatic",
-
-                            development:
-                                true,
-                        },
-                    ]);
-
                     const result =
                         await transformAsync(
                             source,
@@ -1784,6 +1777,15 @@ function createReactRefreshPlugin(
                                 sourceType:
                                     "module",
 
+                                parserOpts:
+                                    parsesJsx
+                                        ? {
+                                            plugins: [
+                                                "jsx",
+                                            ],
+                                        }
+                                        : undefined,
+
                                 presets,
 
                                 plugins: [
@@ -1839,7 +1841,7 @@ ${result.code}
                             transformed,
 
                         loader:
-                            "js",
+                            "jsx",
 
                         resolveDir:
                             path.dirname(