@ecopages/core 0.2.0-beta.29 → 0.2.0-beta.30

package/README.md

@@ -186,31 +186,60 @@ Dependency ownership affects final asset packaging:
 
 ### 5. API Handlers
 
-Add server-side routes using `defineApiHandler`. Register them on your `app` instance before starting:
+Add server-side routes using `defineApiHandler` or the method helpers (`defineGet`, `definePost`, …). Register them on your `app` instance before starting:
 
 ```typescript
-import { defineApiHandler } from '@ecopages/core';
+import { defineApiHandler, defineGet, json } from '@ecopages/core';
 
-export const helloWorld = defineApiHandler({
+export const helloWorld = defineGet({
 	path: '/api/hello',
-	method: 'GET',
 	handler: async ({ response }) => {
 		return response.json({ message: 'Hello World' });
 	},
 });
+
+// Equivalent with an explicit method:
+export const helloWorldAlt = defineApiHandler({
+	path: '/api/hello',
+	method: 'GET',
+	handler: async () => json({ message: 'Hello World' }),
+});
+```
+
+Group related routes with `defineGroupHandler`. Prefer `api.get` / `api.post` helpers inside the `routes` callback:
+
+```typescript
+import { defineGroupHandler } from '@ecopages/core';
+
+export const adminGroup = defineGroupHandler({
+	prefix: '/admin',
+	routes: (api) => [
+		api.get({
+			path: '/',
+			handler: async ({ response }) => response.json({ ok: true }),
+		}),
+		api.post({
+			path: '/items',
+			handler: async ({ response }) => response.status(201).json({ created: true }),
+		}),
+	],
+});
 ```
 
+Standalone response helpers (`json`, `html`, `redirect`) share the same body emission path as `context.response.json()` / `context.response.html()`.
+
+Register a prebuilt handler with `app.add()`. Use `app.get(path, handler)` only when defining the route inline in `app.ts`.
+
 Attach the handler in your `app.ts` entry:
 
 ```typescript
-// app.ts
 import { createApp } from '@ecopages/core/create-app';
 import { helloWorld } from './handlers/hello';
 import appConfig from './eco.config';
 
 const app = await createApp({ appConfig });
 
-app.get(helloWorld); // Register the API handler
+app.add(helloWorld);
 
 await app.start();
 ```
@@ -223,7 +252,7 @@ Use the `create-app` subpath for runtime startup and the root package for standa
 
 ```ts
 import { createApp } from '@ecopages/core/create-app';
-import { defineApiHandler, defineGroupHandler, eco } from '@ecopages/core';
+import { defineApiHandler, defineGet, defineGroupHandler, eco } from '@ecopages/core';
 ```
 
 > [!NOTE]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecopages/core",
-  "version": "0.2.0-beta.29",
+  "version": "0.2.0-beta.30",
   "description": "Core package for Ecopages",
   "keywords": [
     "ecopages",
@@ -17,7 +17,7 @@
     "directory": "packages/core"
   },
   "dependencies": {
-    "@ecopages/file-system": "0.2.0-beta.29",
+    "@ecopages/file-system": "0.2.0-beta.30",
     "@ecopages/logger": "^0.2.3",
     "@ecopages/scripts-injector": "^0.1.5",
     "@oxc-project/runtime": "0.134.0",

package/src/adapters/README.md

@@ -22,9 +22,13 @@ They are not responsible for:
 
 ## Main Areas
 
-- `bun/`: Bun server adapter, lifecycle coordination, bridge, and HMR transport
+- `bun/`: Bun server adapter, lifecycle coordination, bridge, HMR transport, and Bun user WebSocket lifecycle
 - `node/`: internal Node compatibility adapter pieces used by the CLI thin-host path
-- `shared/`: runtime-neutral adapter helpers used by both hosts
+- `shared/`: runtime-neutral adapter helpers used by both hosts, clustered by concern:
+    - `shared/http/` — API response builders, request pipeline, middleware runner, define-api helpers, explicit-static and filesystem matchers
+    - `shared/hmr/` — HMR HTML inject helpers, shared HMR manager, entrypoint registrar
+    - `shared/runtime/` — shared server adapter, route handler, application adapter, static builder, port/bootstrap utilities
+    - `shared/ws/` — WinterCG WebSocket lifecycle helpers and Node HTTP upgrade bridge (Bun-specific user WS lifecycle lives under `bun/`)
 
 ## Ownership Boundary
 

package/src/adapters/abstract/segment-path-matcher.d.ts

@@ -0,0 +1,6 @@
+export declare function normalizeSegmentPath(pathname: string): string;
+export declare function matchApiPathPattern(pattern: string, pathname: string): Record<string, string | string[]> | null;
+export declare function scoreApiPathPattern(pattern: string): number;
+export declare function matchExplicitStaticPathPattern(pattern: string, pathname: string): Record<string, string> | null;
+export declare function matchColonSegmentPath(pattern: string, pathname: string): Record<string, string> | null;
+export declare function scoreColonSegmentPath(pattern: string): number;

package/src/adapters/abstract/segment-path-matcher.js

@@ -0,0 +1,149 @@
+function normalizeSegmentPath(pathname) {
+  if (pathname.length > 1 && pathname.endsWith("/")) {
+    return pathname.slice(0, -1);
+  }
+  return pathname;
+}
+function matchApiPathPattern(pattern, pathname) {
+  const normalizedPattern = normalizeSegmentPath(pattern);
+  const normalizedPathname = normalizeSegmentPath(pathname);
+  const patternSegments = normalizedPattern.split("/").filter(Boolean);
+  const pathSegments = normalizedPathname.split("/").filter(Boolean);
+  const params = {};
+  let patternIndex = 0;
+  let pathIndex = 0;
+  while (patternIndex < patternSegments.length && pathIndex < pathSegments.length) {
+    const patternSegment = patternSegments[patternIndex];
+    const pathSegment = pathSegments[pathIndex];
+    if (patternSegment === "*") {
+      return params;
+    }
+    if (patternSegment.startsWith("[...") && patternSegment.endsWith("]")) {
+      const paramName = patternSegment.slice(4, -1);
+      params[paramName] = pathSegments.slice(pathIndex);
+      return params;
+    }
+    if (patternSegment.startsWith(":")) {
+      params[patternSegment.slice(1)] = pathSegment;
+      patternIndex++;
+      pathIndex++;
+      continue;
+    }
+    if (patternSegment.startsWith("[") && patternSegment.endsWith("]")) {
+      params[patternSegment.slice(1, -1)] = pathSegment;
+      patternIndex++;
+      pathIndex++;
+      continue;
+    }
+    if (patternSegment !== pathSegment) {
+      return null;
+    }
+    patternIndex++;
+    pathIndex++;
+  }
+  if (patternIndex < patternSegments.length) {
+    const remaining = patternSegments.slice(patternIndex);
+    const catchAll = remaining[0];
+    if (remaining.length === 1 && (catchAll === "*" || catchAll.startsWith("[...") && catchAll.endsWith("]"))) {
+      if (catchAll.startsWith("[...")) {
+        const paramName = catchAll.slice(4, -1);
+        params[paramName] = [];
+      }
+      return params;
+    }
+    return null;
+  }
+  if (pathIndex < pathSegments.length) {
+    return null;
+  }
+  return params;
+}
+function scoreApiPathPattern(pattern) {
+  const segments = normalizeSegmentPath(pattern).split("/").filter(Boolean);
+  let score = 0;
+  for (const segment of segments) {
+    if (segment === "*" || segment.startsWith("[...") && segment.endsWith("]")) {
+      score += 10;
+    } else if (segment.startsWith(":") || segment.startsWith("[") && segment.endsWith("]")) {
+      score += 50;
+    } else {
+      score += 100;
+    }
+  }
+  return score;
+}
+function matchExplicitStaticPathPattern(pattern, pathname) {
+  const patternSegments = normalizeSegmentPath(pattern).split("/").filter(Boolean);
+  const pathSegments = normalizeSegmentPath(pathname).split("/").filter(Boolean);
+  if (patternSegments.length !== pathSegments.length) {
+    const lastPattern = patternSegments[patternSegments.length - 1];
+    const isCatchAll = lastPattern?.startsWith("[...") || lastPattern?.startsWith(":...");
+    if (!isCatchAll) {
+      return null;
+    }
+  }
+  const params = {};
+  for (let i = 0; i < patternSegments.length; i++) {
+    const patternPart = patternSegments[i];
+    const pathPart = pathSegments[i];
+    if (patternPart.startsWith(":...") || patternPart.startsWith("[...")) {
+      const paramName = patternPart.replace(/^(:\.\.\.|\[\.\.\.)/, "").replace(/\]$/, "");
+      params[paramName] = pathSegments.slice(i).join("/");
+      return params;
+    }
+    if (patternPart.startsWith(":")) {
+      params[patternPart.slice(1)] = pathPart;
+    } else if (patternPart.startsWith("[") && patternPart.endsWith("]")) {
+      params[patternPart.slice(1, -1)] = pathPart;
+    } else if (patternPart !== pathPart) {
+      return null;
+    }
+  }
+  return params;
+}
+function matchColonSegmentPath(pattern, pathname) {
+  const patternSegments = pattern.split("/").filter(Boolean);
+  const pathSegments = pathname.split("/").filter(Boolean);
+  if (patternSegments.length !== pathSegments.length) {
+    return null;
+  }
+  const params = {};
+  for (let i = 0; i < patternSegments.length; i++) {
+    const patternSegment = patternSegments[i];
+    const pathSegment = pathSegments[i];
+    if (!patternSegment || !pathSegment) {
+      return null;
+    }
+    if (patternSegment.startsWith(":")) {
+      const paramName = patternSegment.slice(1);
+      if (!paramName) {
+        return null;
+      }
+      params[paramName] = pathSegment;
+    } else if (patternSegment !== pathSegment) {
+      return null;
+    }
+  }
+  return params;
+}
+function scoreColonSegmentPath(pattern) {
+  const segments = pattern.split("/").filter(Boolean);
+  let literals = 0;
+  let dynamics = 0;
+  for (const segment of segments) {
+    if (segment.startsWith(":")) {
+      dynamics += 1;
+    } else {
+      literals += 1;
+    }
+  }
+  return literals * 100 - dynamics * 10 + segments.length;
+}
+export {
+  matchApiPathPattern,
+  matchColonSegmentPath,
+  matchExplicitStaticPathPattern,
+  normalizeSegmentPath,
+  scoreApiPathPattern,
+  scoreColonSegmentPath
+};

package/src/adapters/abstract/ws-pattern-matcher.d.ts

@@ -1,60 +1,12 @@
 import type { EcopagesWebSocketHandler } from '../../types/public-types.js';
-/**
- * Pattern matcher for WebSocket route paths.
- *
- * Supports dynamic segments via `:param` syntax. Matches are exact on literal
- * segments and capture dynamic segments into a params object.
- *
- * @example
- * ```ts
- * matchWebSocketPath('/ws/chat/:id', '/ws/chat/abc123')
- * // Returns: { id: 'abc123' }
- *
- * matchWebSocketPath('/ws/chat/:id', '/ws/chat/abc123/messages')
- * // Returns: null (length mismatch)
- *
- * matchWebSocketPath('/ws/chat', '/ws/chat')
- * // Returns: {} (no params)
- * ```
- *
- * @remarks
- * This is a minimal segment-based matcher. It does not support wildcards,
- * optional segments, or catch-all patterns. Those are future concerns.
- *
- * @param pattern - The registered route pattern (e.g. '/ws/chat/:id')
- * @param pathname - The actual request pathname (e.g. '/ws/chat/abc123')
- * @returns A params object if the pattern matches, or null if it does not
- */
-export declare function matchWebSocketPath(pattern: string, pathname: string): Record<string, string> | null;
-/**
- * Represents a matched WebSocket route.
- */
 export type WebSocketRouteMatch = {
     handler: EcopagesWebSocketHandler<any, any>;
     params: Record<string, string>;
     kind: string;
 };
 /**
- * Scores a pattern for specificity ordering.
- *
- * Higher scores win. Rules, in order:
- * 1. More literal segments beats more dynamic segments.
- * 2. Fewer dynamic segments beats more dynamic segments.
- * 3. Longer route (more segments) beats shorter route.
- *
- * @param pattern - The registered route pattern
- * @returns A numeric specificity score
+ * Pattern matcher for WebSocket route paths.
  */
+export declare function matchWebSocketPath(pattern: string, pathname: string): Record<string, string> | null;
 export declare function scoreWebSocketPattern(pattern: string): number;
-/**
- * Find the registered WebSocket handler that best matches a pathname.
- *
- * Iterates through the provided handlers map, computes each pattern's
- * specificity score, and returns the highest-scoring match. Ties resolve
- * to the earliest-registered pattern.
- *
- * @param handlers - The map of registered WebSocket handlers
- * @param pathname - The actual request pathname
- * @returns The best match, or null if no pattern matches
- */
 export declare function findWebSocketRoute(handlers: Map<string, EcopagesWebSocketHandler<any, any>>, pathname: string): WebSocketRouteMatch | null;

package/src/adapters/abstract/ws-pattern-matcher.js

@@ -1,51 +1,20 @@
+import { matchColonSegmentPath, scoreColonSegmentPath } from "./segment-path-matcher.js";
 function matchWebSocketPath(pattern, pathname) {
-  const patternSegments = pattern.split("/").filter(Boolean);
-  const pathSegments = pathname.split("/").filter(Boolean);
-  if (patternSegments.length !== pathSegments.length) {
-    return null;
-  }
-  const params = {};
-  for (let i = 0; i < patternSegments.length; i++) {
-    const patternSegment = patternSegments[i];
-    const pathSegment = pathSegments[i];
-    if (!patternSegment || !pathSegment) {
-      return null;
-    }
-    if (patternSegment.startsWith(":")) {
-      const paramName = patternSegment.slice(1);
-      if (!paramName) {
-        return null;
-      }
-      params[paramName] = pathSegment;
-    } else if (patternSegment !== pathSegment) {
-      return null;
-    }
-  }
-  return params;
+  return matchColonSegmentPath(pattern, pathname);
 }
 function scoreWebSocketPattern(pattern) {
-  const segments = pattern.split("/").filter(Boolean);
-  let literals = 0;
-  let dynamics = 0;
-  for (const segment of segments) {
-    if (segment.startsWith(":")) {
-      dynamics += 1;
-    } else {
-      literals += 1;
-    }
-  }
-  return literals * 100 - dynamics * 10 + segments.length;
+  return scoreColonSegmentPath(pattern);
 }
 function findWebSocketRoute(handlers, pathname) {
   let best = null;
   let index = 0;
   for (const [pattern, handler] of handlers) {
-    const params = matchWebSocketPath(pattern, pathname);
+    const params = matchColonSegmentPath(pattern, pathname);
     if (params === null) {
       index += 1;
       continue;
     }
-    const score = scoreWebSocketPattern(pattern);
+    const score = scoreColonSegmentPath(pattern);
     const match = { handler, params, kind: pattern };
     if (best === null || score > best.score || score === best.score && index < best.index) {
       best = { score, match, index };

package/src/adapters/{shared → bun}/bun-user-websocket-lifecycle.js

@@ -1,5 +1,5 @@
 import { appLogger } from "../../global/app-logger.js";
-import { invokeWebSocketHandlerHook, toWebSocketCloseInfo } from "./websocket-lifecycle.js";
+import { invokeWebSocketHandlerHook, toWebSocketCloseInfo } from "../shared/ws/websocket-lifecycle.js";
 function toUpgradeRequest(ws, runtimeOrigin) {
   const upgradeUrl = ws.data?.upgradeUrl;
   if (upgradeUrl) {

package/src/adapters/bun/create-app.d.ts

@@ -9,8 +9,8 @@
  */
 import type { Server } from 'bun';
 import type { ApiHandlerContext, RouteGroupBuilder } from '../../types/public-types.js';
-import { SharedApplicationAdapter } from '../shared/application-adapter.js';
-import type { RuntimeHost } from '../shared/runtime-host.js';
+import { SharedApplicationAdapter } from '../shared/runtime/application-adapter.js';
+import type { RuntimeHost } from '../shared/runtime/runtime-host.js';
 import type { EcopagesAppOptions } from '../create-app.js';
 import { type BunServerAdapterResult } from './server-adapter.js';
 /**

package/src/adapters/bun/create-app.js

@@ -1,6 +1,6 @@
 import { appLogger } from "../../global/app-logger.js";
-import { SharedApplicationAdapter } from "../shared/application-adapter.js";
-import { resolveRuntimeBinding, resolveStaticRuntimeMode } from "../shared/runtime-app-bootstrap.js";
+import { SharedApplicationAdapter } from "../shared/runtime/application-adapter.js";
+import { resolveRuntimeBinding, resolveStaticRuntimeMode } from "../shared/runtime/runtime-app-bootstrap.js";
 import { startupTrace } from "../../diagnostics/startup-trace.js";
 import { createBunServerAdapter } from "./server-adapter.js";
 import { BunRuntimeHost } from "./runtime-host.js";

package/src/adapters/bun/hmr-manager.d.ts

@@ -2,7 +2,7 @@ import type { WebSocketHandler } from 'bun';
 import type { EcoPagesAppConfig } from '../../types/internal-types.js';
 import type { ClientBridge } from './client-bridge.js';
 import { InMemoryEntrypointDependencyGraph, type EntrypointDependencyGraph } from '../../services/runtime-state/entrypoint-dependency-graph.service.js';
-import { SharedHmrManager } from '../shared/shared-hmr-manager.js';
+import { SharedHmrManager } from '../shared/hmr/shared-hmr-manager.js';
 type BunSocketHandler = WebSocketHandler<unknown>;
 export interface HmrManagerParams {
     appConfig: EcoPagesAppConfig;

package/src/adapters/bun/hmr-manager.js

@@ -2,7 +2,7 @@ import { appLogger } from "../../global/app-logger.js";
 import {
   InMemoryEntrypointDependencyGraph
 } from "../../services/runtime-state/entrypoint-dependency-graph.service.js";
-import { SharedHmrManager } from "../shared/shared-hmr-manager.js";
+import { SharedHmrManager } from "../shared/hmr/shared-hmr-manager.js";
 class HmrManager extends SharedHmrManager {
   wsHandler;
   /**

package/src/adapters/bun/index.d.ts

@@ -1,2 +1,2 @@
 export { BunEcopagesApp, createApp } from './create-app.js';
-export { defineApiHandler, defineGroupHandler, type GroupHandler } from '../shared/define-api-handler.js';
+export { defineApiHandler, defineGroupHandler, defineGet, definePost, definePut, defineDelete, definePatch, defineOptions, defineHead, json, html, redirect, type GroupHandler, } from '../shared/http/define-api-handler.js';

package/src/adapters/bun/index.js

@@ -1,8 +1,31 @@
 import { BunEcopagesApp, createApp } from "./create-app.js";
-import { defineApiHandler, defineGroupHandler } from "../shared/define-api-handler.js";
+import {
+  defineApiHandler,
+  defineGroupHandler,
+  defineGet,
+  definePost,
+  definePut,
+  defineDelete,
+  definePatch,
+  defineOptions,
+  defineHead,
+  json,
+  html,
+  redirect
+} from "../shared/http/define-api-handler.js";
 export {
   BunEcopagesApp,
   createApp,
   defineApiHandler,
-  defineGroupHandler
+  defineDelete,
+  defineGet,
+  defineGroupHandler,
+  defineHead,
+  defineOptions,
+  definePatch,
+  definePost,
+  definePut,
+  html,
+  json,
+  redirect
 };

package/src/adapters/bun/runtime-host.d.ts

@@ -1,5 +1,5 @@
 import type { Server } from 'bun';
-import type { RuntimeHost, RuntimeHostStartOptions } from '../shared/runtime-host.js';
+import type { RuntimeHost, RuntimeHostStartOptions } from '../shared/runtime/runtime-host.js';
 type BunRuntimeProvider = {
     serve(options: Bun.Serve.Options<unknown>): Server<unknown>;
 };

package/src/adapters/bun/runtime-host.js

@@ -1,5 +1,5 @@
 import { getBunRuntime } from "../../utils/runtime.js";
-import { resolveServeRuntimeOrigin } from "../shared/runtime-app-bootstrap.js";
+import { resolveServeRuntimeOrigin } from "../shared/runtime/runtime-app-bootstrap.js";
 class BunRuntimeHost {
   /**
    * Creates a Bun runtime host with an injectable runtime lookup.

package/src/adapters/bun/server-adapter.d.ts

@@ -2,9 +2,9 @@ import type { Server as NodeHttpServer } from 'node:http';
 import type { Server, WebSocketHandler } from 'bun';
 import type { EcoPagesAppConfig } from '../../types/internal-types.js';
 import type { ApiHandler, ErrorHandler, StaticRoute, EcopagesWebSocketHandler } from '../../types/public-types.js';
-import { SharedServerAdapter } from '../shared/server-adapter.js';
+import { SharedServerAdapter } from '../shared/runtime/server-adapter.js';
 import type { ServerAdapterResult } from '../abstract/server-adapter.js';
-import type { StaticPreviewHost } from '../shared/static-preview-host.js';
+import type { StaticPreviewHost } from '../shared/runtime/static-preview-host.js';
 import { ClientBridge } from './client-bridge.js';
 import { HmrManager } from './hmr-manager.js';
 type BunServerInstance = Server<unknown>;
@@ -136,15 +136,6 @@ export declare class BunServerAdapter extends SharedServerAdapter<BunServerAdapt
     attachUserWebSocketUpgrades(server: NodeHttpServer, options?: {
         passthroughUnmatched?: boolean;
     }): void;
-    /**
-     * Returns whether adapter-level HTML responses still need HMR runtime injection.
-     *
-     * @remarks
-     * Filesystem-routed pages are wrapped later in the shared route layer. This
-     * adapter-level check exists for explicit API handlers that return HTML and
-     * would otherwise bypass the route wrapper entirely.
-     */
-    private maybeInjectHmrScript;
     /**
      * Initializes the server adapter's core runtime components.
      */
@@ -189,18 +180,12 @@ export declare class BunServerAdapter extends SharedServerAdapter<BunServerAdapt
     private createHmrAwareWebSocketHandler;
     /**
      * @remarks
-     * When `serveHmrEndpoints` is set, `/_hmr` and `/_hmr_runtime.js` are checked
-     * before user websocket patterns so HMR upgrades are never captured by app routes.
+     * When `serveHmrEndpoints` is set, `/_hmr` is checked before user websocket
+     * patterns so HMR upgrades are never captured by app routes. Runtime assets are
+     * served by `SharedServerAdapter.handleSharedRequest` via `tryHandleAssetRequest`.
      * Production mode with only user handlers skips the HMR branch entirely.
      */
     private wrapFetchWithWebSocketUpgrades;
-    /**
-     * Helper method to retrieve and parse the request body.
-     * Handles JSON and plain text content types.
-     * For FormData (multipart/form-data, x-www-form-urlencoded), use ctx.request.formData() directly.
-     * Returns undefined for unsupported content types.
-     */
-    private retrieveBodyFromRequest;
     /**
      * Composes the base Bun server settings that all runtime modes build from.
      *
@@ -256,11 +241,9 @@ export declare class BunServerAdapter extends SharedServerAdapter<BunServerAdapt
      * Handles HTTP requests by passing them securely to the shared core router adapter.
      *
      * @remarks
-     * Filesystem page responses are wrapped by `ServerRouteHandler`. This
-     * adapter-level pass only covers HTML returned by explicit API handlers,
-     * which bypass that route-layer wrapper and would otherwise miss the
-     * dev HMR runtime — so the HMR script injection happens here, after
-     * the shared handler runs.
+     * HMR HTML injection for API and page responses is owned by
+     * `SharedServerAdapter.handleSharedRequest`. This method only maps the
+     * request into the shared pipeline.
      */
     handleRequest(request: Request): Promise<Response>;
     /**