@chidchanun/bcp 0.1.5 → 0.1.6

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 All notable framework changes are tracked here before release.
 
+## 0.1.6 - Critical CSS and release visibility
+
+### Performance
+
+- Small generated `/bcp.css` stylesheets are inlined into SSR HTML when they are 8 KiB or smaller, removing the stylesheet request from the initial render-critical path.
+- Critical CSS optimization is applied in development and standalone production.
+- Gzip, Brotli and deflate HTML responses are decoded, transformed and re-encoded so response compression remains intact.
+- Applications with CSP policies that do not allow inline styles automatically keep the external `/bcp.css` link instead of breaking page styling.
+- Critical CSS transformation is skipped entirely when the stylesheet is missing or larger than the inline threshold.
+
+### Reliability and release tooling
+
+- Added regression tests for critical CSS inlining, size fallback, closing-style escaping, compressed responses and CSP fallback.
+- Added `release:visibility-check` so an npm release is not considered ready until the exact framework and generator versions are readable from the registry.
+- `release:publish:yes` and `release:resume` now run the registry visibility check after npm accepts the publish.
+
 ## 0.1.5 - Application module boundaries
 
 ### Developer experience

package/README.md

@@ -2,7 +2,7 @@
 
 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.
 
-> Current development version: `0.1.5`. BCP is still pre-1.0 and validates each release candidate before the manual npm publish step.
+> Current development version: `0.1.6`. BCP is still pre-1.0 and validates each release candidate before the manual npm publish step.
 
 ## Quick start
 
@@ -77,6 +77,10 @@ Database helpers generated by `create-bcp-app` include the server-only marker au
 
 See [Application Modules](docs/application-modules.md) for the complete boundary model and examples.
 
+## Tailwind and critical CSS
+
+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.
+
 ## Commands
 
 ```bash
@@ -248,6 +252,8 @@ npm run rc:check
 
 `rc:check` validates tests/release metadata, checks npm package-name availability or ownership, performs `npm publish --dry-run`, and clean-installs both generated tarballs into temporary projects.
 
+After a real publish, `npm run release:visibility-check` verifies that the exact framework and generator versions are readable from the npm registry before the release is treated as ready for installation.
+
 `package:prepare` stages the framework at `.package/bcp`. The default package name is `bcp`; set `BCP_PACKAGE_NAME` when preparing a scoped or alternate package name.
 
 No real npm publish command is run automatically by the repository.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chidchanun/bcp",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "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/server/src/critical-css-proxy.ts

@@ -0,0 +1,559 @@
+import * as http from "node:http";
+import {
+    brotliCompressSync,
+    brotliDecompressSync,
+    deflateSync,
+    gunzipSync,
+    gzipSync,
+    inflateSync,
+} from "node:zlib";
+
+import {
+    canInlineStylesheet,
+    inlineSmallStylesheet,
+} from "./critical-css.js";
+
+export interface CriticalCssProxyOptions {
+    port: number;
+    hostname: string;
+    upstreamPort: number;
+    upstreamHostname: string;
+    cssFile: string;
+}
+
+type SupportedContentEncoding =
+    | "identity"
+    | "gzip"
+    | "br"
+    | "deflate";
+
+export function createCriticalCssProxy(
+    options: CriticalCssProxyOptions
+) {
+    const server =
+        http.createServer(
+            (
+                req,
+                res
+            ) => {
+                const upstream =
+                    http.request({
+                        hostname:
+                            options.upstreamHostname,
+                        port:
+                            options.upstreamPort,
+                        method:
+                            req.method ??
+                            "GET",
+                        path:
+                            req.url ??
+                            "/",
+                        headers: {
+                            ...req.headers,
+                            host:
+                                req.headers.host ??
+                                `${options.hostname}:${options.port}`,
+                        },
+                    });
+
+                upstream.on(
+                    "response",
+                    (upstreamResponse) => {
+                        const encoding =
+                            getSupportedContentEncoding(
+                                upstreamResponse
+                            );
+
+                        if (
+                            !canInlineStylesheet(
+                                options.cssFile
+                            ) ||
+                            !encoding ||
+                            !shouldTransformHtml(
+                                req,
+                                upstreamResponse
+                            )
+                        ) {
+                            writeUpstreamHead(
+                                res,
+                                upstreamResponse
+                            );
+                            upstreamResponse.pipe(
+                                res
+                            );
+                            return;
+                        }
+
+                        void transformHtmlResponse(
+                            res,
+                            upstreamResponse,
+                            options.cssFile,
+                            encoding
+                        );
+                    }
+                );
+
+                upstream.on(
+                    "error",
+                    (error) => {
+                        if (
+                            res.headersSent
+                        ) {
+                            res.destroy(
+                                error
+                            );
+                            return;
+                        }
+
+                        res.writeHead(
+                            502,
+                            {
+                                "Content-Type":
+                                    "text/plain; charset=utf-8",
+                                "Cache-Control":
+                                    "no-store",
+                            }
+                        );
+                        res.end(
+                            "Bad Gateway"
+                        );
+                    }
+                );
+
+                req.pipe(
+                    upstream
+                );
+            }
+        );
+
+    server.keepAliveTimeout =
+        65_000;
+    server.headersTimeout =
+        66_000;
+
+    return {
+        async start(): Promise<void> {
+            await listen(
+                server,
+                options.port,
+                options.hostname
+            );
+        },
+
+        async stop(): Promise<void> {
+            if (
+                !server.listening
+            ) {
+                return;
+            }
+
+            await new Promise<void>(
+                (
+                    resolve,
+                    reject
+                ) => {
+                    server.close(
+                        (error) => {
+                            if (error) {
+                                reject(
+                                    error
+                                );
+                                return;
+                            }
+
+                            resolve();
+                        }
+                    );
+                }
+            );
+        },
+    };
+}
+
+function shouldTransformHtml(
+    req: http.IncomingMessage,
+    response: http.IncomingMessage
+): boolean {
+    if (
+        (req.method ?? "GET").toUpperCase() !==
+        "GET"
+    ) {
+        return false;
+    }
+
+    if (
+        response.statusCode !== 200
+    ) {
+        return false;
+    }
+
+    const contentType =
+        response.headers[
+            "content-type"
+        ];
+    const value =
+        Array.isArray(
+            contentType
+        )
+            ? contentType[0]
+            : contentType;
+
+    return (
+        typeof value === "string" &&
+        /^text\/html\b/i.test(
+            value
+        ) &&
+        allowsInlineStyles(
+            response
+        )
+    );
+}
+
+function allowsInlineStyles(
+    response: http.IncomingMessage
+): boolean {
+    const header =
+        response.headers[
+            "content-security-policy"
+        ];
+    const policies =
+        Array.isArray(
+            header
+        )
+            ? header
+            : header
+                ? [header]
+                : [];
+
+    if (
+        policies.length === 0
+    ) {
+        return true;
+    }
+
+    return policies.every(
+        (policy) =>
+            policyAllowsInlineStyles(
+                policy
+            )
+    );
+}
+
+function policyAllowsInlineStyles(
+    policy: string
+): boolean {
+    const directives =
+        new Map<string, string[]>();
+
+    for (
+        const rawDirective
+        of policy.split(";")
+    ) {
+        const parts =
+            rawDirective
+                .trim()
+                .split(/\s+/)
+                .filter(Boolean);
+
+        if (
+            parts.length === 0
+        ) {
+            continue;
+        }
+
+        directives.set(
+            parts[0].toLowerCase(),
+            parts.slice(1)
+        );
+    }
+
+    for (
+        const name
+        of [
+            "style-src-elem",
+            "style-src",
+            "default-src",
+        ]
+    ) {
+        const sources =
+            directives.get(
+                name
+            );
+
+        if (!sources) {
+            continue;
+        }
+
+        return sources.some(
+            (source) =>
+                source.toLowerCase() ===
+                "'unsafe-inline'"
+        );
+    }
+
+    return true;
+}
+
+async function transformHtmlResponse(
+    res: http.ServerResponse,
+    upstreamResponse: http.IncomingMessage,
+    cssFile: string,
+    encoding: SupportedContentEncoding
+): Promise<void> {
+    try {
+        const chunks:
+            Buffer[] = [];
+
+        for await (
+            const chunk
+            of upstreamResponse
+        ) {
+            chunks.push(
+                Buffer.isBuffer(
+                    chunk
+                )
+                    ? chunk
+                    : Buffer.from(
+                        chunk
+                    )
+            );
+        }
+
+        const decodedBody =
+            decodeBody(
+                Buffer.concat(
+                    chunks
+                ),
+                encoding
+            );
+
+        const html =
+            inlineSmallStylesheet(
+                decodedBody.toString(
+                    "utf8"
+                ),
+                cssFile
+            );
+
+        const responseBody =
+            encodeBody(
+                Buffer.from(
+                    html,
+                    "utf8"
+                ),
+                encoding
+            );
+
+        const headers:
+            http.OutgoingHttpHeaders = {
+                ...upstreamResponse.headers,
+                "content-length":
+                    responseBody.length,
+            };
+
+        delete headers[
+            "transfer-encoding"
+        ];
+        delete headers[
+            "etag"
+        ];
+        delete headers[
+            "content-md5"
+        ];
+
+        if (
+            encoding === "identity"
+        ) {
+            delete headers[
+                "content-encoding"
+            ];
+        }
+
+        writeUpstreamHead(
+            res,
+            upstreamResponse,
+            headers
+        );
+        res.end(
+            responseBody
+        );
+    } catch (error) {
+        if (
+            res.headersSent
+        ) {
+            res.destroy(
+                error instanceof Error
+                    ? error
+                    : undefined
+            );
+            return;
+        }
+
+        res.writeHead(
+            500,
+            {
+                "Content-Type":
+                    "text/plain; charset=utf-8",
+                "Cache-Control":
+                    "no-store",
+            }
+        );
+        res.end(
+            "Internal Server Error"
+        );
+    }
+}
+
+function getSupportedContentEncoding(
+    response: http.IncomingMessage
+): SupportedContentEncoding | null {
+    const header =
+        response.headers[
+            "content-encoding"
+        ];
+    const value =
+        (
+            Array.isArray(
+                header
+            )
+                ? header[0]
+                : header
+        )
+            ?.trim()
+            .toLowerCase();
+
+    if (
+        !value ||
+        value === "identity"
+    ) {
+        return "identity";
+    }
+
+    if (
+        value === "gzip" ||
+        value === "br" ||
+        value === "deflate"
+    ) {
+        return value;
+    }
+
+    return null;
+}
+
+function decodeBody(
+    body: Buffer,
+    encoding: SupportedContentEncoding
+): Buffer {
+    switch (encoding) {
+        case "gzip":
+            return gunzipSync(
+                body
+            );
+        case "br":
+            return brotliDecompressSync(
+                body
+            );
+        case "deflate":
+            return inflateSync(
+                body
+            );
+        default:
+            return body;
+    }
+}
+
+function encodeBody(
+    body: Buffer,
+    encoding: SupportedContentEncoding
+): Buffer {
+    switch (encoding) {
+        case "gzip":
+            return gzipSync(
+                body
+            );
+        case "br":
+            return brotliCompressSync(
+                body
+            );
+        case "deflate":
+            return deflateSync(
+                body
+            );
+        default:
+            return body;
+    }
+}
+
+function writeUpstreamHead(
+    res: http.ServerResponse,
+    upstreamResponse: http.IncomingMessage,
+    headers:
+        http.OutgoingHttpHeaders =
+        upstreamResponse.headers
+): void {
+    const statusCode =
+        upstreamResponse.statusCode ??
+        502;
+
+    if (
+        upstreamResponse.statusMessage
+    ) {
+        res.writeHead(
+            statusCode,
+            upstreamResponse.statusMessage,
+            headers
+        );
+        return;
+    }
+
+    res.writeHead(
+        statusCode,
+        headers
+    );
+}
+
+async function listen(
+    server: http.Server,
+    port: number,
+    hostname: string
+): Promise<void> {
+    await new Promise<void>(
+        (
+            resolve,
+            reject
+        ) => {
+            const onError =
+                (error: Error) => {
+                    server.off(
+                        "listening",
+                        onListening
+                    );
+                    reject(
+                        error
+                    );
+                };
+
+            const onListening =
+                () => {
+                    server.off(
+                        "error",
+                        onError
+                    );
+                    resolve();
+                };
+
+            server.once(
+                "error",
+                onError
+            );
+            server.once(
+                "listening",
+                onListening
+            );
+            server.listen(
+                port,
+                hostname
+            );
+        }
+    );
+}

package/packages/server/src/critical-css.ts

@@ -0,0 +1,132 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export const DEFAULT_INLINE_STYLESHEET_LIMIT =
+    8 * 1024;
+
+export interface InlineStylesheetOptions {
+    href?: string;
+    maxBytes?: number;
+}
+
+export function canInlineStylesheet(
+    cssFile: string,
+    maxBytes =
+        DEFAULT_INLINE_STYLESHEET_LIMIT
+): boolean {
+    assertValidMaxBytes(
+        maxBytes
+    );
+
+    try {
+        const stat =
+            fs.statSync(
+                cssFile
+            );
+
+        return (
+            stat.isFile() &&
+            stat.size <= maxBytes
+        );
+    } catch {
+        return false;
+    }
+}
+
+export function inlineSmallStylesheet(
+    html: string,
+    cssFile: string,
+    options: InlineStylesheetOptions = {}
+): string {
+    const href =
+        options.href ??
+        "/bcp.css";
+    const maxBytes =
+        options.maxBytes ??
+        DEFAULT_INLINE_STYLESHEET_LIMIT;
+
+    assertValidMaxBytes(
+        maxBytes
+    );
+
+    const stylesheetPattern =
+        createStylesheetPattern(
+            href
+        );
+
+    if (
+        !stylesheetPattern.test(
+            html
+        ) ||
+        !canInlineStylesheet(
+            cssFile,
+            maxBytes
+        )
+    ) {
+        return html;
+    }
+
+    const css =
+        fs.readFileSync(
+            cssFile,
+            "utf8"
+        );
+
+    const safeCss =
+        css.replace(
+            /<\/style/gi,
+            "<\\/style"
+        );
+
+    return html.replace(
+        stylesheetPattern,
+        `<style data-bcp-inline-css>${safeCss}</style>`
+    );
+}
+
+export function resolveBcpStylesheetFile(
+    publicDirectory: string
+): string {
+    return path.join(
+        publicDirectory,
+        "bcp.css"
+    );
+}
+
+function assertValidMaxBytes(
+    maxBytes: number
+): void {
+    if (
+        !Number.isFinite(
+            maxBytes
+        ) ||
+        maxBytes < 0
+    ) {
+        throw new Error(
+            "BCP Framework: inline stylesheet maxBytes must be a non-negative finite number."
+        );
+    }
+}
+
+function createStylesheetPattern(
+    href: string
+): RegExp {
+    const escapedHref =
+        escapeRegExp(
+            href
+        );
+
+    return new RegExp(
+        `<link\\b(?=[^>]*\\brel=["']stylesheet["'])(?=[^>]*\\bhref=["']${escapedHref}(?:\\?[^"']*)?["'])[^>]*>`,
+        "i"
+    );
+}
+
+function escapeRegExp(
+    value: string
+): string {
+    return value.replace(
+        /[.*+?^${}()|[\]\\]/g,
+        "\\$&"
+    );
+}

package/packages/server/src/middleware-dev-server.ts

@@ -5,6 +5,10 @@ import type {
     DevServerOptions,
 } from "./index.js";
 
+import {
+    createCriticalCssProxy,
+} from "./critical-css-proxy.js";
+
 import {
     loadProjectMiddleware,
 } from "./middleware-loader.js";
@@ -56,6 +60,12 @@ export function createMiddlewareDevServer(
         > | null =
         null;
 
+    let criticalCssGateway:
+        ReturnType<
+            typeof createCriticalCssProxy
+        > | null =
+        null;
+
     let started =
         false;
 
@@ -68,6 +78,8 @@ export function createMiddlewareDevServer(
             await findFreePort();
         const middlewarePort =
             await findFreePort();
+        const securityPort =
+            await findFreePort();
 
         internalServer =
             createStaticDevServer({
@@ -111,8 +123,10 @@ export function createMiddlewareDevServer(
 
         securityGateway =
             createSecurityProxy({
-                port,
-                hostname,
+                port:
+                    securityPort,
+                hostname:
+                    "127.0.0.1",
                 upstreamPort:
                     middlewarePort,
                 upstreamHostname:
@@ -133,12 +147,48 @@ export function createMiddlewareDevServer(
             throw error;
         }
 
+        criticalCssGateway =
+            createCriticalCssProxy({
+                port,
+                hostname,
+                upstreamPort:
+                    securityPort,
+                upstreamHostname:
+                    "127.0.0.1",
+                cssFile:
+                    path.join(
+                        rootDirectory,
+                        "public",
+                        "bcp.css"
+                    ),
+            });
+
+        try {
+            await criticalCssGateway.start();
+        } catch (error) {
+            await securityGateway.stop();
+            await middlewareGateway.stop();
+            await internalServer.stop();
+            internalServer =
+                null;
+            middlewareGateway =
+                null;
+            securityGateway =
+                null;
+            criticalCssGateway =
+                null;
+            throw error;
+        }
+
         started =
             true;
 
         console.log(
             `[BCP Security] Dev gateway: http://${hostname}:${port}`
         );
+        console.log(
+            `[BCP CSS] Inline /bcp.css when <= 8 KiB and allowed by CSP.`
+        );
         console.log(
             `[BCP Middleware] File: ${path.join(rootDirectory, "middleware.ts")} (optional; .tsx/.js/.jsx also supported)`
         );
@@ -146,6 +196,12 @@ export function createMiddlewareDevServer(
     }
 
     async function stop(): Promise<void> {
+        if (criticalCssGateway) {
+            await criticalCssGateway.stop();
+            criticalCssGateway =
+                null;
+        }
+
         if (securityGateway) {
             await securityGateway.stop();
             securityGateway =
@@ -257,4 +313,4 @@ async function findFreePort(): Promise<number> {
             );
         }
     }
-}
+}

package/packages/server/src/standalone-production-runtime-v6.ts

@@ -0,0 +1,205 @@
+import * as net from "node:net";
+import path from "node:path";
+
+import {
+    createCriticalCssProxy,
+} from "./critical-css-proxy.js";
+
+import {
+    createStandaloneProductionServer as createBaseStandaloneProductionServer,
+    type StandaloneApiRoute,
+    type StandalonePageRoute,
+    type StandaloneProductionServerOptions as BaseStandaloneProductionServerOptions,
+} from "./standalone-production-runtime-v5.js";
+
+export type {
+    StandaloneApiRoute,
+    StandalonePageRoute,
+};
+
+export interface StandaloneProductionServerOptions
+    extends BaseStandaloneProductionServerOptions {}
+
+export function createStandaloneProductionServer(
+    options: StandaloneProductionServerOptions
+) {
+    let baseServer:
+        ReturnType<
+            typeof createBaseStandaloneProductionServer
+        > | null =
+        null;
+
+    let criticalCssProxy:
+        ReturnType<
+            typeof createCriticalCssProxy
+        > | null =
+        null;
+
+    let started =
+        false;
+
+    async function start(): Promise<void> {
+        if (started) {
+            return;
+        }
+
+        const internalPort =
+            await findFreePort();
+
+        baseServer =
+            createBaseStandaloneProductionServer({
+                ...options,
+                port:
+                    internalPort,
+                hostname:
+                    "127.0.0.1",
+            });
+
+        await baseServer.start();
+
+        criticalCssProxy =
+            createCriticalCssProxy({
+                port:
+                    options.port,
+                hostname:
+                    options.hostname,
+                upstreamPort:
+                    internalPort,
+                upstreamHostname:
+                    "127.0.0.1",
+                cssFile:
+                    path.join(
+                        options.buildDirectory,
+                        "public",
+                        "bcp.css"
+                    ),
+            });
+
+        try {
+            await criticalCssProxy.start();
+        } catch (error) {
+            await baseServer.stop();
+            baseServer =
+                null;
+            criticalCssProxy =
+                null;
+            throw error;
+        }
+
+        started =
+            true;
+
+        console.log(
+            `[BCP CSS] Inline /bcp.css when <= 8 KiB.`
+        );
+        console.log("");
+    }
+
+    async function stop(): Promise<void> {
+        if (criticalCssProxy) {
+            await criticalCssProxy.stop();
+            criticalCssProxy =
+                null;
+        }
+
+        if (baseServer) {
+            await baseServer.stop();
+            baseServer =
+                null;
+        }
+
+        started =
+            false;
+    }
+
+    return {
+        start,
+        stop,
+    };
+}
+
+async function findFreePort(): Promise<number> {
+    const server =
+        net.createServer();
+
+    try {
+        await new Promise<void>(
+            (
+                resolve,
+                reject
+            ) => {
+                const onError =
+                    (error: Error) => {
+                        server.off(
+                            "listening",
+                            onListening
+                        );
+                        reject(
+                            error
+                        );
+                    };
+
+                const onListening =
+                    () => {
+                        server.off(
+                            "error",
+                            onError
+                        );
+                        resolve();
+                    };
+
+                server.once(
+                    "error",
+                    onError
+                );
+                server.once(
+                    "listening",
+                    onListening
+                );
+                server.listen(
+                    0,
+                    "127.0.0.1"
+                );
+            }
+        );
+
+        const address =
+            server.address();
+
+        if (
+            !address ||
+            typeof address ===
+                "string"
+        ) {
+            throw new Error(
+                "BCP Framework: could not allocate critical CSS production port."
+            );
+        }
+
+        return address.port;
+    } finally {
+        if (
+            server.listening
+        ) {
+            await new Promise<void>(
+                (
+                    resolve,
+                    reject
+                ) => {
+                    server.close(
+                        (error) => {
+                            if (error) {
+                                reject(
+                                    error
+                                );
+                                return;
+                            }
+
+                            resolve();
+                        }
+                    );
+                }
+            );
+        }
+    }
+}

package/packages/server/src/standalone-production-server.ts

@@ -3,4 +3,4 @@ export {
     type StandaloneApiRoute,
     type StandalonePageRoute,
     type StandaloneProductionServerOptions,
-} from "./standalone-production-runtime-v5.js";
+} from "./standalone-production-runtime-v6.js";