@mandujs/core 0.30.0 → 0.32.0

package/src/runtime/server.ts

@@ -84,6 +84,11 @@ import {
   type ComposedHandler,
 } from "../middleware/compose";
 import type { Middleware } from "../middleware/define";
+// Phase 18.λ — scheduler wiring (statically imported so `startServer` stays
+// synchronous; the cost of unused code is trivial — `defineCron` is a thin
+// wrapper around `Bun.cron`).
+import { defineCron as schedulerDefineCron } from "../scheduler";
+import { setActiveSchedulerRegistration } from "../middleware/scheduler-cron";
 import { createFetchHandler } from "./handler";
 import { wrapBunWebSocket, type WSUpgradeData } from "../filling/ws";
 import { handleImageRequest } from "./image-handler";
@@ -91,6 +96,14 @@ import { extractShellHtml, createPPRResponse } from "./ppr";
 import { isRedirectResponse } from "./redirect";
 import { isNotFoundResponse } from "./not-found";
 import { newId } from "../id";
+// Phase 18.κ — typed RPC dispatch (tRPC-like). See
+// `packages/core/src/contract/rpc.ts` + `docs/architect/typed-rpc.md`.
+import {
+  matchRpcPath,
+  dispatchRpc,
+  registerRpc,
+  clearRpcRegistry,
+} from "../contract/rpc";
 import { handleMetadataRoute as dispatchMetadataRoute } from "../routes/metadata-routes";
 import {
   DEFAULT_PRERENDER_DIR,
@@ -104,6 +117,20 @@ import {
   buildPayloadFromError,
   shouldInjectOverlay,
 } from "../dev-error-overlay";
+// Phase 18.μ — i18n dispatch. `resolveLocale()` is pure (no side effects),
+// `createTranslator()` binds a per-request `t()` to the registry.
+import {
+  resolveLocale,
+  createTranslator,
+  isI18nDefinition,
+  isMessageRegistry,
+} from "../i18n";
+import type {
+  I18nDefinition,
+  ResolvedLocale,
+  Translator,
+} from "../i18n/types";
+import type { MessageRegistry } from "../i18n/message-registry";
 
 export interface RateLimitOptions {
   windowMs?: number;
@@ -504,6 +531,64 @@ export interface ServerOptions {
    * `secureMiddleware`, `rateLimitMiddleware`).
    */
   middleware?: Middleware[];
+  /**
+   * Phase 18.κ — tRPC-like typed RPC endpoints.
+   *
+   * Keys map to `/api/rpc/<name>/<method>` routes. Each value is a
+   * `defineRpc()` result (see `@mandujs/core/contract/rpc`). Populating
+   * this field at `startServer()` time registers every endpoint with
+   * the global RPC registry; the dispatcher runs BEFORE β's route
+   * matcher so RPC routes never collide with file-system API routes.
+   *
+   * Typically threaded from `ManduConfig.rpc.endpoints`.
+   */
+  rpc?: {
+    endpoints?: Record<string, import("../contract/rpc").RpcDefinition<import("../contract/rpc").RpcProcedureRecord>>;
+  };
+  /**
+   * Phase 18.λ — declarative cron scheduler.
+   *
+   * When `jobs` is non-empty and `disabled !== true`, `startServer()`
+   * instantiates a `CronRegistration` via `defineCron(jobs)`, calls
+   * `.start()` after the HTTP listener is bound, and wires the handle
+   * into `stop()` so the returned `ManduServer.stop()` also drains any
+   * in-flight cron tick before returning. Jobs whose `runOn` omits
+   * `"bun"` are registered but never fire on the local Bun host — they
+   * still appear in `status()` so dashboards can render their existence.
+   *
+   * Typically threaded from `ManduConfig.scheduler`.
+   */
+  scheduler?: {
+    jobs?: import("../scheduler").CronDef[];
+    disabled?: boolean;
+  };
+  /**
+   * Phase 18.μ — first-class i18n. Threaded from `ManduConfig.i18n`.
+   *
+   * When populated, the runtime dispatcher:
+   *   1. resolves the active locale BEFORE route dispatch (via
+   *      {@link resolveLocale}) using the configured strategy;
+   *   2. attaches `ctx.locale` (ResolvedLocale) + `ctx.t` (typed
+   *      translator) to every loader / handler invocation;
+   *   3. stamps `Vary: Accept-Language` + `Content-Language` on all
+   *      page responses so upstream caches key on locale;
+   *   4. when `strategy === "path-prefix"` and the incoming URL
+   *      carries no locale prefix AND no override cookie, redirects
+   *      `/` → `/<defaultLocale>` so browsers reach a locale-scoped
+   *      URL (Next.js parity).
+   *
+   * Omitting this block keeps the runtime branch-free — the hot path
+   * incurs zero overhead when i18n is disabled.
+   */
+  i18n?: I18nDefinition;
+  /**
+   * Phase 18.μ — optional message registry bound to `ctx.t`. Created via
+   * `defineMessages({ en: {...}, ko: {...} })`. When omitted but `i18n`
+   * is set, `ctx.locale` is populated but `ctx.t` stays `undefined` —
+   * projects that manage their own translation layer (e.g. react-intl)
+   * use `ctx.locale.code` and ignore `ctx.t`.
+   */
+  messages?: MessageRegistry;
 }
 
 export interface ManduServer {
@@ -692,6 +777,19 @@ export interface ServerRegistrySettings {
    * `ServerOptions.middleware` at {@link startServer} time.
    */
   middlewareChain?: ComposedHandler;
+  /**
+   * Phase 18.μ — resolved i18n definition. `undefined` means "no i18n
+   * configured at boot" (hot path is branch-free). Wired from
+   * `ServerOptions.i18n`.
+   */
+  i18n?: I18nDefinition;
+  /**
+   * Phase 18.μ — message registry bound to {@link i18n}. When both are
+   * set, the runtime builds a per-request `ctx.t` via
+   * `createTranslator()`. When only `i18n` is set, `ctx.t` stays
+   * `undefined` and user code is responsible for its own translations.
+   */
+  messages?: MessageRegistry;
 }
 
 export class ServerRegistry {
@@ -1565,6 +1663,15 @@ async function handleRequestWithTracing(
         });
       }
     }
+    // Phase 18.μ — stamp locale hint on error responses too.
+    const errI18nState = i18nRequestState.get(req);
+    if (errI18nState && !errorResponse.headers.has("Content-Language")) {
+      try {
+        errorResponse.headers.set("Content-Language", errI18nState.locale.code);
+      } catch {
+        // Some adapters freeze headers on error responses — ignore.
+      }
+    }
     return errorResponse;
   }
 
@@ -1598,6 +1705,28 @@ async function handleRequestWithTracing(
     }
   }
 
+  // Phase 18.μ — stamp locale-sensitive caching hints onto the final
+  // response. `Vary: Accept-Language, Cookie` ensures upstream caches
+  // key correctly per locale signal; `Content-Language` surfaces the
+  // resolved locale for SEO / screen-reader parity. Only stamped when
+  // i18n is configured AND the request was actually resolved — the hot
+  // path is branch-free when `i18n` is absent.
+  const i18nState = i18nRequestState.get(req);
+  if (i18nState) {
+    const existingVary = result.value.headers.get("Vary");
+    const varyParts = new Set(
+      (existingVary ? existingVary.split(",") : [])
+        .map((s) => s.trim())
+        .filter(Boolean)
+    );
+    varyParts.add("Accept-Language");
+    varyParts.add("Cookie");
+    result.value.headers.set("Vary", [...varyParts].join(", "));
+    if (!result.value.headers.has("Content-Language")) {
+      result.value.headers.set("Content-Language", i18nState.locale.code);
+    }
+  }
+
   return result.value;
 }
 
@@ -1864,6 +1993,7 @@ async function loadPageData(
       // Filling의 loader 실행
       if (registration.filling?.hasLoader()) {
         const ctx = new ManduContext(req, params);
+        attachI18nToContext(ctx, req);
         // DX-3: loader may return OR throw a redirect Response. Both are
         // short-circuits — if we detect one, skip SSR and hand the Response
         // to the caller with pending cookies merged in.
@@ -1984,6 +2114,7 @@ async function loadPageData(
       }
       if (filling?.hasLoader?.()) {
         const ctx = new ManduContext(req, params);
+        attachI18nToContext(ctx, req);
         // DX-3 / Phase 6.3: same redirect + notFound handling as the
         // PageHandler path above. notFound is checked first so both
         // short-circuits remain symmetric.
@@ -2153,6 +2284,7 @@ async function loadLayoutData(
           const filling = exported as ManduFilling;
           if (filling.hasLoader()) {
             const ctx = new ManduContext(req, params);
+            attachI18nToContext(ctx, req);
             const data = await filling.executeLoader(ctx);
             // DX-3: layout loaders are NOT allowed to redirect. They share
             // the pipeline with a page loader and we can only honor one
@@ -2386,15 +2518,27 @@ async function renderPageSSR(
       ? route.streaming
       : settings.streaming;
 
-    // Issue #198 — Pre-resolve async server components before handing off
-    // to React's SSR engines. `renderToString` (non-streaming path) does
-    // not support async components; `renderToReadableStream` does, but
-    // the shell-gen step in streaming-ssr also falls through
-    // `collectStreamingHeadTags` → `renderToString`. Resolving up-front
-    // gives consistent, synchronous trees to both paths and keeps the
-    // user-visible contract (`export default async function Page() {...}`
-    // and `export default async function Layout() {...}`) working end to end.
-    app = (await resolveAsyncElement(app)) as React.ReactElement;
+    // Issue #198 / Phase 18.ξ — Async server component resolution policy.
+    //
+    // Non-streaming path (`renderToString`) cannot handle async components,
+    // so we MUST pre-resolve the tree up-front.
+    //
+    // Streaming path (`renderToReadableStream`, React 19) supports async
+    // components natively and is designed around progressive flushing. If
+    // we pre-resolve here, the caller blocks until every async component
+    // settles before the shell can be emitted — defeating the entire point
+    // of streaming (`TTFB` regresses from shell-ready to slowest-component).
+    // So in streaming mode we hand React the raw async tree. Head tags
+    // pushed from async components are captured by `renderToStream`'s
+    // `buildHtmlTail` (late-head injection) via `use-head`. The streaming
+    // shell-gen's `collectStreamingHeadTags` pre-pass uses `renderToString`
+    // internally and will throw on async trees — its try/catch already
+    // handles that case and returns an empty string, so the early shell
+    // emission is still correct; the late-head script fills in any
+    // metadata emitted during the async render.
+    if (!useStreaming) {
+      app = (await resolveAsyncElement(app)) as React.ReactElement;
+    }
 
     if (useStreaming) {
       const streamingResponse = await renderStreamingResponse(app, {
@@ -2623,6 +2767,7 @@ async function renderNotFoundPage(
     let loaderData: unknown = { message };
     if (registration.filling?.hasLoader()) {
       const ctx = new ManduContext(req, params);
+      attachI18nToContext(ctx, req);
       try {
         const returned = await registration.filling.executeLoader(ctx);
         loaderData = returned !== undefined ? returned : { message };
@@ -3199,6 +3344,66 @@ async function tryServePrerendered(
   return new Response(body, { status: 200, headers });
 }
 
+// ─── Phase 18.μ — request-scoped i18n state ──────────────────────────────
+/**
+ * Per-request locale state keyed by the `Request` object. The runtime
+ * dispatcher populates this right before `handleRequestInternal` returns
+ * to route-specific paths; `handlePageRoute` / `handleApiRoute` read it
+ * when creating `ManduContext` and attach via `ctx._setI18n(...)`.
+ *
+ * A WeakMap is used so completed requests release their entries
+ * automatically — no explicit cleanup needed on the hot path.
+ *
+ * @internal
+ */
+const i18nRequestState = new WeakMap<
+  Request,
+  { locale: ResolvedLocale; translator?: Translator }
+>();
+
+/**
+ * Phase 18.μ — expose the stashed locale state for `filling` /
+ * `handlePageRoute` / `handleApiRoute`. Returns `undefined` when i18n
+ * is disabled OR the request predates dispatch (internal callers).
+ *
+ * @internal
+ */
+export function getRequestI18n(
+  req: Request
+): { locale: ResolvedLocale; translator?: Translator } | undefined {
+  return i18nRequestState.get(req);
+}
+
+/**
+ * Phase 18.μ — attach i18n state to a freshly-constructed `ManduContext`.
+ * No-op when i18n is disabled. Called by every callsite that instantiates
+ * `new ManduContext(req, …)` so `ctx.locale` + `ctx.t` are populated
+ * before loader / handler execution.
+ *
+ * @internal
+ */
+function attachI18nToContext(ctx: ManduContext, req: Request): void {
+  const state = i18nRequestState.get(req);
+  if (state) {
+    ctx._setI18n(state.locale, state.translator);
+  }
+}
+
+/**
+ * Helper: returns the URL's first segment if it matches a known locale.
+ * Extracted so the inline μ dispatch block stays readable.
+ */
+function stripLocaleForRedirectCheck(
+  pathname: string,
+  locales: readonly string[]
+): string | undefined {
+  if (pathname.length < 2) return undefined;
+  const slashIdx = pathname.indexOf("/", 1);
+  const first = slashIdx === -1 ? pathname.slice(1) : pathname.slice(1, slashIdx);
+  return locales.includes(first) ? first : undefined;
+}
+// ─── End Phase 18.μ ──────────────────────────────────────────────────────
+
 async function handleRequestInternal(
   req: Request,
   router: Router,
@@ -3228,6 +3433,92 @@ async function handleRequestInternal(
     return ok(prerendered);
   }
 
+  // ─── Phase 18.μ — i18n dispatch ─────────────────────────────────────────
+  // Runs AFTER γ's prerendered check (static HTML per-locale is already
+  // handled by path-prefix synthesis at build time) and BEFORE ζ's cache
+  // lookup (cache keys include the resolved locale via `Vary:
+  // Accept-Language`).
+  //
+  //   1. Resolve the active locale via `resolveLocale()` — the strategy
+  //      switches determines URL / cookie / header precedence.
+  //   2. For `strategy: 'path-prefix'`: when the incoming URL carries no
+  //      locale prefix (root or locale-less path) AND the resolution
+  //      came from `default` / `fallback`, we emit a 307 redirect to
+  //      `/<locale><rest>` so the user lands on a locale-scoped URL.
+  //      Cookie / header signals "win" over the default — no redirect
+  //      when the user explicitly preferred a non-default locale.
+  //   3. Stash the resolved locale on the `registry.__perRequest` map
+  //      indexed by the request so downstream `handlePageRoute` /
+  //      `handleApiRoute` can mount it onto `ctx` via `_setI18n()`.
+  //
+  // Zero overhead when `settings.i18n` is undefined — the `if` falls
+  // through and the hot path runs exactly as Phase 18.λ's baseline.
+  let resolvedLocaleForRequest: ResolvedLocale | undefined;
+  let translatorForRequest: Translator | undefined;
+  if (settings.i18n) {
+    resolvedLocaleForRequest = resolveLocale(req, settings.i18n);
+
+    // Path-prefix strategy: URL has no locale prefix AND resolver picked
+    // a non-default locale from cookie/header → redirect to prefixed URL
+    // so the user lands on a locale-scoped URL (Next.js parity).
+    //
+    // Excluded paths (never redirected, always locale-neutral):
+    //   - `/api/*`  — API routes use `Accept-Language` header; JSON
+    //     clients rarely want an HTML redirect.
+    //   - `/_mandu/*`, `/.mandu/*` — framework internals.
+    //   - `/sitemap.xml`, `/robots.txt`, etc. — metadata routes live
+    //     at site root across all locales.
+    if (
+      settings.i18n.strategy === "path-prefix" &&
+      (req.method === "GET" || req.method === "HEAD") &&
+      !pathname.startsWith("/api/") &&
+      !pathname.startsWith("/_mandu/") &&
+      !pathname.startsWith("/.mandu/") &&
+      !pathname.startsWith("/__kitchen") &&
+      !pathname.startsWith("/__mandu/") &&
+      pathname !== "/sitemap.xml" &&
+      pathname !== "/robots.txt" &&
+      pathname !== "/llms.txt" &&
+      pathname !== "/manifest.webmanifest"
+    ) {
+      const urlLocale = stripLocaleForRedirectCheck(pathname, settings.i18n.locales);
+      if (!urlLocale && resolvedLocaleForRequest.code !== settings.i18n.defaultLocale) {
+        const targetPath = `/${resolvedLocaleForRequest.code}${pathname === "/" ? "" : pathname}`;
+        const targetUrl = new URL(targetPath + url.search, req.url);
+        const redirectRes = new Response(null, {
+          status: 307,
+          headers: {
+            Location: targetUrl.toString(),
+            Vary: "Accept-Language, Cookie",
+            "Content-Language": resolvedLocaleForRequest.code,
+          },
+        });
+        return ok(redirectRes);
+      }
+    }
+
+    // Build translator if a registry is wired up.
+    if (settings.messages) {
+      translatorForRequest = createTranslator(settings.messages, {
+        activeLocale: resolvedLocaleForRequest.code,
+        defaultLocale: settings.i18n.defaultLocale,
+        fallbackLocale: settings.i18n.fallback,
+      });
+    }
+
+    // Stash on request-scoped map so downstream context creation (inside
+    // `handlePageRoute` / `handleApiRoute`) can pick them up without
+    // threading extra args through every call site. `i18nRequestState`
+    // is a WeakMap — no memory retention after the request completes.
+    if (resolvedLocaleForRequest) {
+      i18nRequestState.set(req, {
+        locale: resolvedLocaleForRequest,
+        translator: translatorForRequest,
+      });
+    }
+  }
+  // ─── End Phase 18.μ ─────────────────────────────────────────────────────
+
   // 1. 정적 파일 서빙 시도 (최우선)
   // Edge runtimes (Cloudflare Workers, etc.) have no filesystem — skip and
   // let the platform's asset pipeline (Wrangler [assets], Vercel _static, …)
@@ -3325,6 +3616,47 @@ async function handleRequestInternal(
   }
   // ─── End Phase 18.ε ──────────────────────────────────────────────────────
 
+  // ─── Phase 18.κ — typed RPC dispatch ──────────────────────────────────────
+  // Runs AFTER γ's prerendered pass-through (handled earlier at step 0.5),
+  // AFTER ζ's ISR/SWR cache check (per-route, inside handlePageRoute), and
+  // BEFORE β's file-system route dispatch below. The canonical URL shape is
+  //
+  //   POST /api/rpc/<endpoint>/<method>
+  //
+  // with JSON body `{ input: <value> }`. The dispatcher:
+  //   1. matches `/api/rpc/<name>/<method>` via `matchRpcPath()` (returns
+  //      `null` for any other path — then we fall through to β),
+  //   2. looks up the registered `RpcDefinition` in the module-level
+  //      `rpcRegistry` (populated by `registerRpc` at boot from
+  //      `ServerOptions.rpc.endpoints`),
+  //   3. validates the request body against `procedure.input` (Zod),
+  //      invokes `procedure.handler`, validates the return value against
+  //      `procedure.output` (Zod), and ships a
+  //      `{ ok: true, data } | { ok: false, error }` JSON envelope.
+  //
+  // All failure paths return structured envelopes — never throws — so the
+  // outer request handler's 5xx catch is unreachable on the happy path.
+  // See `packages/core/src/contract/rpc.ts` and
+  // `docs/architect/typed-rpc.md`.
+  {
+    const rpcMatch = matchRpcPath(pathname);
+    if (rpcMatch) {
+      const rpcResponse = await dispatchRpc(
+        req,
+        rpcMatch.endpoint,
+        rpcMatch.method,
+        { isDev: settings.isDev }
+      );
+      if (settings.cors && isCorsRequest(req)) {
+        const corsOptions: CorsOptions =
+          typeof settings.cors === "object" ? settings.cors : {};
+        return ok(applyCorsToResponse(rpcResponse, req, corsOptions));
+      }
+      return ok(rpcResponse);
+    }
+  }
+  // ─── End Phase 18.κ ───────────────────────────────────────────────────────
+
   // 3. 라우트 매칭
   const match = router.match(pathname);
   if (!match) {
@@ -3340,6 +3672,7 @@ async function handleRequestInternal(
         let loaderData: unknown = { message: "Not Found" };
         if (registration.filling?.hasLoader()) {
           const ctx = new ManduContext(req, {});
+          attachI18nToContext(ctx, req);
           try {
             const returned = await registration.filling.executeLoader(ctx);
             loaderData = returned !== undefined ? returned : { message: "Not Found" };
@@ -3523,8 +3856,28 @@ export function startServer(manifest: RoutesManifest, options: ServerOptions = {
     observability: observabilityOption,
     prerender: prerenderOption,
     middleware: middlewareOption,
+    rpc: rpcOption,
+    scheduler: schedulerOption,
+    i18n: i18nOption,
+    messages: messagesOption,
   } = options;
 
+  // Phase 18.μ — validate i18n + messages shape. Both are branded via
+  // `defineI18n()` / `defineMessages()`; reject any raw object so user
+  // typos fail fast at boot instead of on first request.
+  if (i18nOption !== undefined && !isI18nDefinition(i18nOption)) {
+    throw new Error(
+      "[mandu] ServerOptions.i18n must be the return value of defineI18n(). " +
+        "Import { defineI18n } from '@mandujs/core/i18n'."
+    );
+  }
+  if (messagesOption !== undefined && !isMessageRegistry(messagesOption)) {
+    throw new Error(
+      "[mandu] ServerOptions.messages must be the return value of defineMessages(). " +
+        "Import { defineMessages } from '@mandujs/core/i18n'."
+    );
+  }
+
   // Phase 18.ε — build the request-level middleware chain once at boot.
   // `compose()` returns a passthrough when the list is empty; storing
   // `undefined` for "no middleware" keeps the hot path branch-free.
@@ -3605,10 +3958,28 @@ export function startServer(manifest: RoutesManifest, options: ServerOptions = {
     tracer: tracerInstance.enabled ? tracerInstance : undefined,
     prerender: prerenderSettings,
     middlewareChain,
+    i18n: i18nOption,
+    messages: messagesOption,
   };
 
   registry.rateLimiter = rateLimitOptions ? new MemoryRateLimiter() : null;
 
+  // ─── Phase 18.κ — register RPC endpoints from options ──────────────────
+  // The RPC registry is module-scoped (shared across all server
+  // instances in this process). Clearing first keeps repeated
+  // `startServer()` calls in tests deterministic — otherwise a stale
+  // endpoint from a prior run could answer a later instance's requests.
+  //
+  // This runs once at boot; HMR-time re-registration goes through the
+  // exported `registerRpc()` from `@mandujs/core/contract/rpc`.
+  clearRpcRegistry();
+  if (rpcOption?.endpoints) {
+    for (const [name, definition] of Object.entries(rpcOption.endpoints)) {
+      registerRpc(name, definition);
+    }
+  }
+  // ─── End Phase 18.κ ────────────────────────────────────────────────────
+
   // ─── Phase 18.ζ — ISR/SWR 캐시 초기화 ──────────────────────────────────
   // `cacheOption` 는 `true` | `false` | `CacheStore` | `CacheConfig` 를 받는다:
   //   - `true`          → MemoryCacheStore(1000) 를 기본값으로 생성.
@@ -3788,12 +4159,64 @@ export function startServer(manifest: RoutesManifest, options: ServerOptions = {
     }
   }
 
+  // ─── Phase 18.λ — declarative cron scheduler ────────────────────────────
+  // Boot the scheduler AFTER the HTTP listener is live so a malformed cron
+  // expression (caught by validateCronExpression) surfaces alongside the
+  // other boot errors rather than aborting the server. `startServer` is
+  // synchronous by contract, so we use the already-imported scheduler
+  // module rather than `await import`.
+  let schedulerRegistration: import("../scheduler").CronRegistration | null = null;
+  const jobDefs = schedulerOption?.jobs ?? [];
+  const schedulerDisabled = schedulerOption?.disabled === true;
+  if (jobDefs.length > 0 && !schedulerDisabled) {
+    try {
+      schedulerRegistration = schedulerDefineCron(jobDefs);
+      schedulerRegistration.start();
+      setActiveSchedulerRegistration(schedulerRegistration);
+      const bunJobCount = Object.keys(schedulerRegistration.status()).filter(
+        (name) => {
+          const def = jobDefs.find((j) => j.name === name);
+          const runOn = def?.runOn && def.runOn.length > 0 ? def.runOn : ["bun", "workers"];
+          return runOn.includes("bun");
+        },
+      ).length;
+      console.log(
+        `⏰ Scheduler: ${bunJobCount} cron job(s) registered on Bun runtime` +
+          (jobDefs.length !== bunJobCount
+            ? ` (${jobDefs.length - bunJobCount} workers-only — see wrangler.toml)`
+            : ""),
+      );
+    } catch (err) {
+      // Scheduler failures MUST NOT crash the server — a bad cron string is
+      // a developer error, but the HTTP surface should keep serving. Log
+      // loudly and leave the registration null.
+      console.error(
+        "❌ [scheduler] failed to start — HTTP server continues without cron jobs:",
+        err instanceof Error ? err.message : err,
+      );
+    }
+  }
+
   return {
     server,
     router,
     registry,
     stop: () => {
       registry.kitchen?.stop();
+      // Fire-and-forget the async scheduler drain so `stop()` stays
+      // synchronous for backwards compatibility with existing consumers.
+      // Tests that need to await drain can reach for `registration.stop()`
+      // directly; `server.stop()` triggers shutdown but doesn't block on
+      // in-flight cron handler completion here.
+      if (schedulerRegistration) {
+        const reg = schedulerRegistration;
+        schedulerRegistration = null;
+        void reg.stop()
+          .then(() => setActiveSchedulerRegistration(null))
+          .catch((err) => {
+            console.error("[scheduler] shutdown error:", err);
+          });
+      }
       server.stop();
     },
   };

package/src/runtime/ssr.ts

@@ -590,6 +590,15 @@ export async function resolveAsyncElement(node: ReactNode): Promise<ReactNode> {
   // Clone with the resolved children. React.cloneElement preserves the
   // element's key, ref, and internal `$$typeof` markers — a plain spread
   // does not.
+  //
+  // #212 — when resolvedChildren is an array of siblings, spread it back
+  // to the variadic form so React's variadic-children heuristic kicks in
+  // and does NOT demand keys (the original JSX was variadic too — no key
+  // was required). Passing a single array argument would trigger spurious
+  // "missing key" warnings for every sibling.
+  if (Array.isArray(resolvedChildren)) {
+    return React.cloneElement(element, undefined, ...resolvedChildren);
+  }
   return React.cloneElement(element, undefined, resolvedChildren);
 }