@gracile/engine 0.9.0 → 0.9.1

package/dist/server/request-pipeline.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Pure, testable pipeline steps extracted from the request handler.
+ *
+ * Each function here is a focused stage of the Gracile request lifecycle.
+ * They are composed by `createGracileHandler` in `./request.ts`.
+ *
+ * @internal
+ */
+import { Readable } from 'node:stream';
+import type { Logger, ViteDevServer } from 'vite';
+import { renderRouteTemplate } from '../render/route-template.js';
+import type { RouteInfos } from '../routes/match.js';
+import type { GracileConfig } from '../user-config.js';
+export type StandardResponse = {
+    response: Response;
+    body?: never;
+    init?: never;
+};
+export type ResponseWithNodeReadable = {
+    response?: never;
+    body: Readable;
+    init: ResponseInit;
+};
+export type HandlerResult = StandardResponse | ResponseWithNodeReadable | null;
+export declare const CONTENT_TYPE_HTML: {
+    readonly 'Content-Type': "text/html";
+};
+export declare const PREMISE_REGEXES: {
+    readonly properties: RegExp;
+    readonly document: RegExp;
+};
+/** Describes which premises endpoint was requested, if any. */
+export interface PremisesDescriptor {
+    propertiesOnly: boolean;
+    documentOnly: boolean;
+}
+/**
+ * Strip the `/__…` suffix so hidden-sibling URLs (premises) resolve to
+ * the parent route.
+ *
+ * @example
+ * rewriteHiddenRoutes('http://localhost/blog/__index.props.json')
+ * // → 'http://localhost/blog/'
+ */
+export declare function rewriteHiddenRoutes(url: string): string;
+/**
+ * Determine if the incoming request targets a premises endpoint
+ * (`__index.props.json` or `__index.doc.html`) and whether the config
+ * allows it.
+ *
+ * @returns A descriptor when premises are enabled, or `null` when not.
+ * @throws  When a premise URL is hit but premises are not enabled.
+ */
+export declare function resolvePremises(requestedUrl: string, gracileConfig: GracileConfig): PremisesDescriptor | null;
+export interface ExecuteHandlerOptions {
+    routeInfos: RouteInfos;
+    method: string;
+    request: Request;
+    fullUrl: string;
+    locals: unknown;
+    responseInit: ResponseInit;
+    premises: PremisesDescriptor | null;
+    routeTemplateOptions: Parameters<typeof renderRouteTemplate>[0];
+}
+/**
+ * Result from `executeHandler`:
+ *
+ * - `{ type: 'response', value }` — return this response directly
+ * - `{ type: 'output', value }` — pass to response building
+ * - `{ type: 'fallthrough' }` — no handler, proceed to template-only render
+ */
+export type ExecuteHandlerResult = {
+    type: 'response';
+    value: StandardResponse;
+} | {
+    type: 'output';
+    value: Readable | Response | null;
+} | {
+    type: 'fallthrough';
+};
+/**
+ * Dispatch the user's route handler (top-level function or method-map).
+ *
+ * This determines whether to call the handler, which method to use,
+ * and whether to short-circuit with premises or a 405.
+ */
+export declare function executeHandler(options: ExecuteHandlerOptions): Promise<ExecuteHandlerResult>;
+/**
+ * Render a page that has no handler — just a document/template.
+ * Handles premises short-circuits.
+ */
+export declare function renderWithoutHandler(options: {
+    premises: PremisesDescriptor | null;
+    routeTemplateOptions: Parameters<typeof renderRouteTemplate>[0];
+}): Promise<StandardResponse | Readable | null>;
+export declare function isRedirect(response: Response): {
+    location: string;
+} | null;
+/**
+ * Convert a handler/render output (Response or Readable stream) into
+ * the final `HandlerResult` shape expected by adapters.
+ */
+export declare function buildResponse(options: {
+    output: Readable | Response | null;
+    responseInit: ResponseInit;
+    vite: ViteDevServer | undefined;
+    logger: Logger;
+}): HandlerResult;
+//# sourceMappingURL=request-pipeline.d.ts.map

package/dist/server/request-pipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-pipeline.d.ts","sourceRoot":"","sources":["../../src/server/request-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAIvC,OAAO,KAAK,EAAc,MAAM,EAAE,aAAa,EAAE,MAAM,MAAM,CAAC;AAE9D,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAIvD,MAAM,MAAM,gBAAgB,GAAG;IAC9B,QAAQ,EAAE,QAAQ,CAAC;IACnB,IAAI,CAAC,EAAE,KAAK,CAAC;IACb,IAAI,CAAC,EAAE,KAAK,CAAC;CACb,CAAC;AACF,MAAM,MAAM,wBAAwB,GAAG;IACtC,QAAQ,CAAC,EAAE,KAAK,CAAC;IACjB,IAAI,EAAE,QAAQ,CAAC;IACf,IAAI,EAAE,YAAY,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG,gBAAgB,GAAG,wBAAwB,GAAG,IAAI,CAAC;AAE/E,eAAO,MAAM,iBAAiB;;CAA2C,CAAC;AAE1E,eAAO,MAAM,eAAe;;;CAGlB,CAAC;AAEX,+DAA+D;AAC/D,MAAM,WAAW,kBAAkB;IAClC,cAAc,EAAE,OAAO,CAAC;IACxB,YAAY,EAAE,OAAO,CAAC;CACtB;AAID;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEvD;AAID;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC9B,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,aAAa,GAC1B,kBAAkB,GAAG,IAAI,CAY3B;AAaD,MAAM,WAAW,qBAAqB;IACrC,UAAU,EAAE,UAAU,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,YAAY,EAAE,YAAY,CAAC;IAC3B,QAAQ,EAAE,kBAAkB,GAAG,IAAI,CAAC;IACpC,oBAAoB,EAAE,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAAC;CAChE;AAED;;;;;;GAMG;AACH,MAAM,MAAM,oBAAoB,GAC7B;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,gBAAgB,CAAA;CAAE,GAC7C;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,QAAQ,GAAG,QAAQ,GAAG,IAAI,CAAA;CAAE,GACrD;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,CAAC;AAE3B;;;;;GAKG;AACH,wBAAsB,cAAc,CACnC,OAAO,EAAE,qBAAqB,GAC5B,OAAO,CAAC,oBAAoB,CAAC,CAyF/B;AAID;;;GAGG;AACH,wBAAsB,oBAAoB,CAAC,OAAO,EAAE;IACnD,QAAQ,EAAE,kBAAkB,GAAG,IAAI,CAAC;IACpC,oBAAoB,EAAE,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAAC;CAChE,GAAG,OAAO,CAAC,gBAAgB,GAAG,QAAQ,GAAG,IAAI,CAAC,CAoB9C;AAID,wBAAgB,UAAU,CAAC,QAAQ,EAAE,QAAQ,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAM1E;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE;IACtC,MAAM,EAAE,QAAQ,GAAG,QAAQ,GAAG,IAAI,CAAC;IACnC,YAAY,EAAE,YAAY,CAAC;IAC3B,IAAI,EAAE,aAAa,GAAG,SAAS,CAAC;IAChC,MAAM,EAAE,MAAM,CAAC;CACf,GAAG,aAAa,CAqDhB"}

package/dist/server/request-pipeline.js

@@ -0,0 +1,198 @@
+/**
+ * Pure, testable pipeline steps extracted from the request handler.
+ *
+ * Each function here is a focused stage of the Gracile request lifecycle.
+ * They are composed by `createGracileHandler` in `./request.ts`.
+ *
+ * @internal
+ */
+import { Readable } from 'node:stream';
+import * as assert from '@gracile/internal-utils/assertions';
+import { renderRouteTemplate } from '../render/route-template.js';
+export const CONTENT_TYPE_HTML = { 'Content-Type': 'text/html' };
+export const PREMISE_REGEXES = {
+    properties: /\/__(.*?)\.props\.json$/,
+    document: /\/__(.*?)\.doc\.html$/,
+};
+// ── 1. Rewrite hidden route siblings ─────────────────────────────────
+/**
+ * Strip the `/__…` suffix so hidden-sibling URLs (premises) resolve to
+ * the parent route.
+ *
+ * @example
+ * rewriteHiddenRoutes('http://localhost/blog/__index.props.json')
+ * // → 'http://localhost/blog/'
+ */
+export function rewriteHiddenRoutes(url) {
+    return url.replace(/\/__(.*)$/, '/');
+}
+// ── 2. Resolve premises ──────────────────────────────────────────────
+/**
+ * Determine if the incoming request targets a premises endpoint
+ * (`__index.props.json` or `__index.doc.html`) and whether the config
+ * allows it.
+ *
+ * @returns A descriptor when premises are enabled, or `null` when not.
+ * @throws  When a premise URL is hit but premises are not enabled.
+ */
+export function resolvePremises(requestedUrl, gracileConfig) {
+    const propertiesOnly = PREMISE_REGEXES.properties.test(requestedUrl);
+    const documentOnly = PREMISE_REGEXES.document.test(requestedUrl);
+    const allowPremises = Boolean(gracileConfig.pages?.premises?.expose);
+    if (allowPremises === false && (propertiesOnly || documentOnly))
+        throw new Error('Accessed a page premise but they are not activated. You must enable `pages.premises.expose`.');
+    if (allowPremises)
+        return { propertiesOnly, documentOnly };
+    return null;
+}
+/**
+ * Dispatch the user's route handler (top-level function or method-map).
+ *
+ * This determines whether to call the handler, which method to use,
+ * and whether to short-circuit with premises or a 405.
+ */
+export async function executeHandler(options) {
+    const { routeInfos, method, request, fullUrl, locals, responseInit, premises, routeTemplateOptions, } = options;
+    const handler = routeInfos.routeModule.handler;
+    const shouldDispatch = ('handler' in routeInfos.routeModule && handler !== undefined) ||
+        // NOTE: When a handler exists but has no GET key, and the request
+        // method is not GET, we still dispatch to let it handle the method.
+        (handler && 'GET' in handler === false && method !== 'GET');
+    if (!shouldDispatch)
+        return { type: 'fallthrough' };
+    // Build the frozen context passed to the user handler.
+    let providedLocals = {};
+    if (locals && assert.isUnknownObject(locals))
+        providedLocals = locals;
+    const routeContext = Object.freeze({
+        request,
+        url: new URL(fullUrl),
+        responseInit,
+        params: routeInfos.params,
+        locals: providedLocals,
+    });
+    const hasTopLevelHandler = typeof handler === 'function';
+    if (!hasTopLevelHandler && !(method in handler)) {
+        const statusText = `This route doesn't handle the \`${method}\` method!`;
+        return {
+            type: 'response',
+            value: {
+                response: new Response(statusText, { status: 405, statusText }),
+            },
+        };
+    }
+    const handlerWithMethod = hasTopLevelHandler
+        ? handler
+        : handler[method];
+    if (typeof handlerWithMethod !== 'function')
+        throw new TypeError('Handler must be a function.');
+    const handlerOutput = await Promise.resolve(handlerWithMethod(routeContext));
+    // User returned a raw Response — pass it through.
+    if (assert.isResponseOrPatchedResponse(handlerOutput))
+        return { type: 'output', value: handlerOutput };
+    // User returned data — merge into routeInfos.props for template rendering.
+    routeTemplateOptions.routeInfos.props = hasTopLevelHandler
+        ? handlerOutput
+        : { [method]: handlerOutput };
+    // Short-circuit for premises.
+    if (premises?.documentOnly) {
+        const { document } = await renderRouteTemplate(routeTemplateOptions);
+        return {
+            type: 'response',
+            value: {
+                response: new Response(document, {
+                    headers: { ...CONTENT_TYPE_HTML },
+                }),
+            },
+        };
+    }
+    if (premises?.propertiesOnly)
+        return {
+            type: 'response',
+            value: {
+                response: Response.json(routeTemplateOptions.routeInfos.props),
+            },
+        };
+    const output = await renderRouteTemplate(routeTemplateOptions).then((r) => r.output);
+    return { type: 'output', value: output };
+}
+// ── 4. Render without handler (template-only) ────────────────────────
+/**
+ * Render a page that has no handler — just a document/template.
+ * Handles premises short-circuits.
+ */
+export async function renderWithoutHandler(options) {
+    const { premises, routeTemplateOptions } = options;
+    if (premises?.documentOnly) {
+        const { document } = await renderRouteTemplate(routeTemplateOptions);
+        return {
+            response: new Response(document, {
+                headers: { ...CONTENT_TYPE_HTML },
+            }),
+        };
+    }
+    if (premises?.propertiesOnly)
+        return {
+            response: Response.json(routeTemplateOptions.routeInfos.props || {}),
+        };
+    const output = await renderRouteTemplate(routeTemplateOptions).then((r) => r.output);
+    return output;
+}
+// ── 5. Build the final response from output ──────────────────────────
+export function isRedirect(response) {
+    const location = response.headers.get('location');
+    if (response.status >= 300 && response.status <= 303 && location) {
+        return { location };
+    }
+    return null;
+}
+/**
+ * Convert a handler/render output (Response or Readable stream) into
+ * the final `HandlerResult` shape expected by adapters.
+ */
+export function buildResponse(options) {
+    const { output, responseInit, vite, logger } = options;
+    // Direct Response pass-through (e.g. from handler returning Response)
+    if (assert.isResponseOrPatchedResponse(output)) {
+        const redirect = isRedirect(output);
+        if (redirect?.location)
+            return {
+                response: Response.redirect(redirect.location, output.status),
+            };
+        return { response: output };
+    }
+    // Readable stream — the SSR page render
+    if (output instanceof Readable) {
+        responseInit.headers = {
+            ...responseInit.headers,
+            ...CONTENT_TYPE_HTML,
+        };
+        return {
+            body: output.on('error', (error) => {
+                const errorMessage = `[SSR Error] There was an error while rendering a template chunk on server-side.\n` +
+                    `It was omitted from the resulting HTML.\n`;
+                if (vite) {
+                    logger.error(errorMessage + error.stack);
+                    const payload = {
+                        type: 'error',
+                        err: {
+                            name: 'StreamingError',
+                            message: errorMessage,
+                            stack: error.stack ?? 'No stack trace available',
+                            hint: 'This is often caused by a wrong template location dynamic interpolation.',
+                            cause: error,
+                        },
+                    };
+                    setTimeout(() => {
+                        vite.hot.send(payload);
+                    }, 200);
+                }
+                else {
+                    logger.error(errorMessage);
+                }
+            }),
+            init: responseInit,
+        };
+    }
+    return null;
+}

package/dist/server/request.d.ts

@@ -1,27 +1,14 @@
-import { Readable } from 'node:stream';
 import type { Logger, ViteDevServer } from 'vite';
 import type * as R from '../routes/route.js';
 import type { GracileConfig } from '../user-config.js';
-type StandardResponse = {
-    response: Response;
-    body?: never;
-    init?: never;
-};
-type ResponseWithNodeReadable = {
-    response?: never;
-    body: Readable;
-    init: ResponseInit;
-};
+import { type HandlerResult } from './request-pipeline.js';
 export interface AdapterOptions {
     logger?: Logger;
 }
 /**
  * The underlying handler interface that you can use to build your own adapter.
  */
-export type GracileHandler = (request: Request, locals?: unknown) => Promise<StandardResponse | ResponseWithNodeReadable | null>;
-export declare function isRedirect(response: Response): {
-    location: string;
-} | null;
+export type GracileHandler = (request: Request, locals?: unknown) => Promise<HandlerResult>;
 export declare function createGracileHandler({ vite, routes, routeImports, routeAssets, root, serverMode, gracileConfig, }: {
     vite?: ViteDevServer | undefined;
     routes: R.RoutesManifest;
@@ -31,5 +18,5 @@ export declare function createGracileHandler({ vite, routes, routeImports, route
     serverMode?: boolean | undefined;
     gracileConfig: GracileConfig;
 }): GracileHandler;
-export {};
+export { type StandardResponse, type ResponseWithNodeReadable, isRedirect, } from './request-pipeline.js';
 //# sourceMappingURL=request.d.ts.map

package/dist/server/request.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"request.d.ts","sourceRoot":"","sources":["../../src/server/request.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAOvC,OAAO,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,MAAM,CAAC;AAQlD,OAAO,KAAK,KAAK,CAAC,MAAM,oBAAoB,CAAC;AAC7C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAIvD,KAAK,gBAAgB,GAAG;IAAE,QAAQ,EAAE,QAAQ,CAAC;IAAC,IAAI,CAAC,EAAE,KAAK,CAAC;IAAC,IAAI,CAAC,EAAE,KAAK,CAAA;CAAE,CAAC;AAC3E,KAAK,wBAAwB,GAAG;IAC/B,QAAQ,CAAC,EAAE,KAAK,CAAC;IACjB,IAAI,EAAE,QAAQ,CAAC;IACf,IAAI,EAAE,YAAY,CAAC;CACnB,CAAC;AAEF,MAAM,WAAW,cAAc;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,CAC5B,OAAO,EAAE,OAAO,EAChB,MAAM,CAAC,EAAE,OAAO,KACZ,OAAO,CAAC,gBAAgB,GAAG,wBAAwB,GAAG,IAAI,CAAC,CAAC;AASjE,wBAAgB,UAAU,CAAC,QAAQ,EAAE,QAAQ,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAO1E;AAED,wBAAgB,oBAAoB,CAAC,EACpC,IAAI,EACJ,MAAM,EACN,YAAY,EACZ,WAAW,EACX,IAAI,EACJ,UAAU,EACV,aAAa,GACb,EAAE;IACF,IAAI,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;IACjC,MAAM,EAAE,CAAC,CAAC,cAAc,CAAC;IACzB,YAAY,CAAC,EAAE,CAAC,CAAC,aAAa,GAAG,SAAS,CAAC;IAC3C,WAAW,CAAC,EAAE,CAAC,CAAC,YAAY,CAAC;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACjC,aAAa,EAAE,aAAa,CAAC;CAC7B,kBAgRA"}
+{"version":3,"file":"request.d.ts","sourceRoot":"","sources":["../../src/server/request.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,MAAM,CAAC;AAOlD,OAAO,KAAK,KAAK,CAAC,MAAM,oBAAoB,CAAC;AAC7C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEvD,OAAO,EACN,KAAK,aAAa,EAOlB,MAAM,uBAAuB,CAAC;AAE/B,MAAM,WAAW,cAAc;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,CAC5B,OAAO,EAAE,OAAO,EAChB,MAAM,CAAC,EAAE,OAAO,KACZ,OAAO,CAAC,aAAa,CAAC,CAAC;AAE5B,wBAAgB,oBAAoB,CAAC,EACpC,IAAI,EACJ,MAAM,EACN,YAAY,EACZ,WAAW,EACX,IAAI,EACJ,UAAU,EACV,aAAa,GACb,EAAE;IACF,IAAI,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;IACjC,MAAM,EAAE,CAAC,CAAC,cAAc,CAAC;IACzB,YAAY,CAAC,EAAE,CAAC,CAAC,aAAa,GAAG,SAAS,CAAC;IAC3C,WAAW,CAAC,EAAE,CAAC,CAAC,YAAY,CAAC;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACjC,aAAa,EAAE,aAAa,CAAC;CAC7B,kBAuIA;AAyBD,OAAO,EACN,KAAK,gBAAgB,EACrB,KAAK,wBAAwB,EAC7B,UAAU,GACV,MAAM,uBAAuB,CAAC"}

package/dist/server/request.js

@@ -1,24 +1,11 @@
 import { Readable } from 'node:stream';
-import * as assert from '@gracile/internal-utils/assertions';
 import { getLogger } from '@gracile/internal-utils/logger/helpers';
 import c from 'picocolors';
-// import { GracileError } from '../errors/errors.js';
 import { builtIn404Page, builtInErrorPage } from '../errors/pages.js';
 import { renderRouteTemplate } from '../render/route-template.js';
 import { renderLitTemplate } from '../render/lit-ssr.js';
 import { getRoute } from '../routes/match.js';
-const CONTENT_TYPE_HTML = { 'Content-Type': 'text/html' };
-const PREMISE_REGEXES = {
-    properties: /\/__(.*?)\.props\.json$/,
-    document: /\/__(.*?)\.doc\.html$/,
-};
-export function isRedirect(response) {
-    const location = response.headers.get('location');
-    if (response.status >= 300 && response.status <= 303 && location) {
-        return { location };
-    }
-    return null;
-}
+import { CONTENT_TYPE_HTML, rewriteHiddenRoutes, resolvePremises, executeHandler, renderWithoutHandler, buildResponse, } from './request-pipeline.js';
 export function createGracileHandler({ vite, routes, routeImports, routeAssets, root, serverMode, gracileConfig, }) {
     const logger = getLogger();
     const middleware = async (request, locals) => {
@@ -28,33 +15,42 @@ export function createGracileHandler({ vite, routes, routeImports, routeAssets,
             emitViteBetterError =
                 await import('../errors/create-vite-better-error.js').then(({ emitViteBetterError: error }) => error);
         try {
-            // MARK: Rewrite hidden route siblings
-            const fullUrl = requestedUrl.replace(/\/__(.*)$/, '/');
-            // MARK: Setup premises
-            const propertiesOnly = PREMISE_REGEXES.properties.test(requestedUrl);
-            const documentOnly = PREMISE_REGEXES.document.test(requestedUrl);
-            const allowPremises = Boolean(gracileConfig.pages?.premises?.expose);
-            if (allowPremises === false && (propertiesOnly || documentOnly))
-                throw new Error('Accessed a page premise but they are not activated. You must enable `pages.premises.expose`.');
-            const premises = allowPremises ? { propertiesOnly, documentOnly } : null;
-            // MARK: Get route infos
+            // MARK: 1. Rewrite hidden route siblings
+            const fullUrl = rewriteHiddenRoutes(requestedUrl);
+            // MARK: 2. Setup premises
+            const premises = resolvePremises(requestedUrl, gracileConfig);
+            // MARK: 3. Route resolution + 404 fallback
             const routeOptions = {
                 url: fullUrl,
                 vite,
                 routes,
                 routeImports,
+                trailingSlash: gracileConfig.trailingSlash ?? 'ignore',
             };
             const responseInit = {};
-            let routeInfos = await getRoute(routeOptions);
-            // MARK: 404
+            const routeResult = await getRoute(routeOptions);
+            // Trailing slash redirect (301 for GET, 308 for other methods)
+            if (routeResult && 'redirect' in routeResult) {
+                const redirectUrl = new URL(routeResult.redirect, fullUrl).href;
+                const status = method === 'GET' ? 301 : 308;
+                return { response: Response.redirect(redirectUrl, status) };
+            }
+            let routeInfos = routeResult;
             if (routeInfos === null) {
                 responseInit.status = 404;
+                // Use 'ignore' for the internal 404 lookup to avoid redirect loops.
                 const url = new URL('/404/', fullUrl).href;
-                const options = { ...routeOptions, url };
-                const notFound = await getRoute(options);
-                routeInfos = notFound;
+                const options = {
+                    ...routeOptions,
+                    url,
+                    trailingSlash: 'ignore',
+                };
+                const notFoundResult = await getRoute(options);
+                routeInfos =
+                    notFoundResult && !('redirect' in notFoundResult)
+                        ? notFoundResult
+                        : null;
             }
-            // MARK: fallback 404
             if (routeInfos === null) {
                 const page = builtIn404Page(new URL(fullUrl).pathname, Boolean(vite));
                 return {
@@ -66,7 +62,7 @@ export function createGracileHandler({ vite, routes, routeImports, routeAssets,
             const routeTemplateOptions = {
                 url: fullUrl,
                 vite,
-                mode: 'dev', // vite && vite.config.mode === 'dev' ? 'dev' : 'build',
+                mode: 'dev',
                 routeAssets,
                 root,
                 serverMode,
@@ -77,153 +73,38 @@ export function createGracileHandler({ vite, routes, routeImports, routeAssets,
             logger.info(`[${c.yellow(method)}] ${c.yellow(fullUrl)}`, {
                 timestamp: true,
             });
+            // MARK: 4. Handler dispatch
             let output;
-            let providedLocals = {};
-            if (locals && assert.isUnknownObject(locals))
-                providedLocals = locals;
-            // MARK: Server handler
-            const handler = routeInfos.routeModule.handler;
-            if (('handler' in routeInfos.routeModule && handler !== undefined) ||
-                // TODO: Explain this condition
-                (handler && 'GET' in handler === false && method !== 'GET')) {
-                const routeContext = Object.freeze({
-                    request,
-                    url: new URL(fullUrl),
-                    responseInit,
-                    params: routeInfos.params,
-                    locals: providedLocals,
-                });
-                // MARK: Run user middleware
-                // NOTE: Experimental
-                /// eslint-disable-next-line no-inner-declarations
-                // async function useHandler() {}
-                // if (vite) {
-                // 	const middleware = await vite
-                // 		.ssrLoadModule('/src/middleware.ts')
-                // 		.catch(() => null)
-                // 		.then((m) => m.default);
-                // 	if (middleware)
-                // 		await middleware(
-                // 			routeContext,
-                // 			async () => {
-                // 				await useHandler();
-                // 			},
-                // 		);
-                // 	else await useHandler();
-                // } else {
-                // 	await useHandler();
-                // }
-                //
-                // MARK: Handler(s)
-                const hasTopLevelHandler = typeof handler === 'function';
-                if (hasTopLevelHandler || method in handler) {
-                    const handlerWithMethod = hasTopLevelHandler
-                        ? handler
-                        : handler[method];
-                    if (typeof handlerWithMethod !== 'function')
-                        throw new TypeError('Handler must be a function.');
-                    const handlerOutput = await Promise.resolve(handlerWithMethod(routeContext));
-                    if (assert.isResponseOrPatchedResponse(handlerOutput))
-                        output = handlerOutput;
-                    else {
-                        routeTemplateOptions.routeInfos.props = hasTopLevelHandler
-                            ? handlerOutput
-                            : { [method]: handlerOutput };
-                        if (premises?.documentOnly) {
-                            const { document } = await renderRouteTemplate(routeTemplateOptions);
-                            return {
-                                response: new Response(document, {
-                                    headers: { ...CONTENT_TYPE_HTML },
-                                }),
-                            };
-                        }
-                        if (premises?.propertiesOnly)
-                            return {
-                                response: Response.json(routeTemplateOptions.routeInfos.props),
-                            };
-                        output = await renderRouteTemplate(routeTemplateOptions).then((r) => r.output);
-                    }
-                    // MARK: No GET, render page
-                }
-                else {
-                    const statusText = `This route doesn't handle the \`${method}\` method!`;
-                    return {
-                        response: new Response(statusText, { status: 405, statusText }),
-                    };
-                }
+            const handlerResult = await executeHandler({
+                routeInfos,
+                method,
+                request,
+                fullUrl,
+                locals,
+                responseInit,
+                premises,
+                routeTemplateOptions,
+            });
+            if (handlerResult.type === 'response')
+                return handlerResult.value;
+            if (handlerResult.type === 'output') {
+                output = handlerResult.value;
             }
             else {
-                if (premises?.documentOnly) {
-                    const { document } = await renderRouteTemplate(routeTemplateOptions);
-                    return {
-                        response: new Response(document, {
-                            headers: { ...CONTENT_TYPE_HTML },
-                        }),
-                    };
-                }
-                if (premises?.propertiesOnly)
-                    return {
-                        response: Response.json(routeTemplateOptions.routeInfos.props || {}),
-                    };
-                output = await renderRouteTemplate(routeTemplateOptions).then((r) => r.output);
-            }
-            // MARK: Return response
-            // NOTE: try directly with the requestPonyfill. This might not be necessary
-            if (assert.isResponseOrPatchedResponse(output)) {
-                const redirect = isRedirect(output);
-                if (redirect?.location)
-                    return {
-                        response: Response.redirect(redirect.location, output.status),
-                    };
-                return { response: output };
-                // MARK: Stream page render
-            }
-            // MARK: Page stream error
-            if (output instanceof Readable) {
-                responseInit.headers = {
-                    ...responseInit.headers,
-                    ...CONTENT_TYPE_HTML,
-                };
-                return {
-                    body: output.on('error', (error) => {
-                        const errorMessage = `[SSR Error] There was an error while rendering a template chunk on server-side.\n` +
-                            `It was omitted from the resulting HTML.\n`;
-                        if (vite) {
-                            logger.error(errorMessage + error.stack);
-                            // emitViteBetterError(new GracileError(GracileErrorData.FailedToGlobalLogger), vite);
-                            const payload = {
-                                type: 'error',
-                                // FIXME: Use the emitViteBetterError instead (but flaky for now with streaming)
-                                // err: new GracileError({}),
-                                err: {
-                                    name: 'StreamingError',
-                                    message: errorMessage,
-                                    stack: error.stack,
-                                    hint: 'This is often caused by a wrong template location dynamic interpolation.',
-                                    cause: error,
-                                    // highlightedCode: error.message,
-                                },
-                            };
-                            //
-                            setTimeout(() => {
-                                // @ts-expect-error ...........
-                                vite.hot.send(payload);
-                                // NOTE: Arbitrary value. Lower seems to be too fast, higher is not guaranteed to work.
-                            }, 200);
-                        }
-                        else {
-                            logger.error(errorMessage);
-                        }
-                    }),
-                    init: responseInit,
-                };
+                // MARK: 5. Template-only render (no handler)
+                const renderResult = await renderWithoutHandler({
+                    premises,
+                    routeTemplateOptions,
+                });
+                if (renderResult && 'response' in renderResult)
+                    return renderResult;
+                output = renderResult;
             }
-            return null;
+            // MARK: 6. Build final response
+            return buildResponse({ output, responseInit, vite, logger });
             // MARK: Errors
         }
         catch (error) {
-            // const safeError = createSafeError(error);
-            // TODO: User defined dev/runtime 500 error
             const ultimateErrorPage = vite && emitViteBetterError
                 ? await emitViteBetterError({ vite, error: error })
                 : await renderLitTemplate(builtInErrorPage(error.name));
@@ -238,3 +119,25 @@ export function createGracileHandler({ vite, routes, routeImports, routeAssets,
     };
     return middleware;
 }
+// MARK: Run user middleware
+// NOTE: Experimental
+/// eslint-disable-next-line no-inner-declarations
+// async function useHandler() {}
+// if (vite) {
+// 	const middleware = await vite
+// 		.ssrLoadModule('/src/middleware.ts')
+// 		.catch(() => null)
+// 		.then((m) => m.default);
+// 	if (middleware)
+// 		await middleware(
+// 			routeContext,
+// 			async () => {
+// 				await useHandler();
+// 			},
+// 		);
+// 	else await useHandler();
+// } else {
+// 	await useHandler();
+// }
+//
+export { isRedirect, } from './request-pipeline.js';

package/dist/test/init.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=init.d.ts.map

package/dist/test/init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/test/init.ts"],"names":[],"mappings":""}

package/dist/test/init.js

@@ -0,0 +1,7 @@
+/**
+ * Side-effect import: initializes the Gracile logger globally.
+ * Import this at the top of any engine unit test that touches modules
+ * which call `getLogger()` at module scope.
+ */
+import { createLogger } from '@gracile/internal-utils/logger/helpers';
+createLogger();