@mandujs/core 0.39.2 → 0.40.0

package/src/config/mandu.ts

@@ -618,6 +618,45 @@ export interface ManduConfig {
     /** Domain → locale map; required when strategy === "domain". */
     domains?: Record<string, LocaleCode>;
   };
+  /**
+   * Issue #235 — Brain LLM adapter selection.
+   *
+   * Mandu is a CONNECTOR for third-party LLMs, not an LLM owner. Cloud
+   * adapters forward requests using the user's own OAuth credentials,
+   * obtained via `mandu brain login --provider=<name>` and stored in
+   * the OS keychain. No API keys ever live in Mandu's process memory;
+   * Mandu-controlled billing is not a thing.
+   *
+   * Fields:
+   *   - `adapter`          — Which connector to use. Default `"auto"`.
+   *                          Auto resolves in priority order:
+   *                          openai → anthropic → ollama → template.
+   *                          Explicit values pin the choice but still
+   *                          degrade to template when the dependency is
+   *                          unreachable (no hard failures).
+   *   - `openai.model`     — Override the OpenAI model (default
+   *                          `"gpt-4o-mini"`).
+   *   - `anthropic.model`  — Override the Anthropic model (default
+   *                          `"claude-haiku-4-5-20251001"`).
+   *   - `ollama.model`     — Override the local Ollama model (default
+   *                          `"ministral-3:3b"`).
+   *   - `telemetryOptOut`  — When `true`, cloud adapters are disabled
+   *                          entirely regardless of stored tokens. The
+   *                          resolver falls to ollama/template. Use for
+   *                          privacy-strict environments.
+   *
+   * Omitting this block is equivalent to `{ adapter: "auto" }`.
+   *
+   * @see `@mandujs/core/brain/adapters` for the resolver implementation.
+   * @see `docs/brain/oauth-adapters.md` (when authored).
+   */
+  brain?: {
+    adapter?: "auto" | "openai" | "anthropic" | "ollama" | "template";
+    openai?: { model?: string };
+    anthropic?: { model?: string };
+    ollama?: { model?: string; baseUrl?: string };
+    telemetryOptOut?: boolean;
+  };
 }
 
 export const CONFIG_FILES = [

package/src/config/validate.ts

@@ -587,6 +587,48 @@ const I18nConfigSchema = z
     }
   });
 
+/**
+ * Issue #235 — Brain adapter block (strict).
+ *
+ * All fields optional; omitting the block is equivalent to
+ * `{ adapter: "auto" }`. `telemetryOptOut: true` forces the resolver
+ * to skip every cloud tier regardless of stored tokens.
+ *
+ * Per-provider sub-blocks are strict so stale `apiKey` / `endpoint` /
+ * etc. keys from ad-hoc configs fail fast — Mandu's connector model
+ * does NOT accept inline API keys.
+ */
+const BrainOpenAIConfigSchema = z
+  .object({
+    model: z.string().min(1).optional(),
+  })
+  .strict();
+
+const BrainAnthropicConfigSchema = z
+  .object({
+    model: z.string().min(1).optional(),
+  })
+  .strict();
+
+const BrainOllamaConfigSchema = z
+  .object({
+    model: z.string().min(1).optional(),
+    baseUrl: z.string().url().optional(),
+  })
+  .strict();
+
+const BrainConfigSchema = z
+  .object({
+    adapter: z
+      .enum(["auto", "openai", "anthropic", "ollama", "template"])
+      .default("auto"),
+    openai: BrainOpenAIConfigSchema.optional(),
+    anthropic: BrainAnthropicConfigSchema.optional(),
+    ollama: BrainOllamaConfigSchema.optional(),
+    telemetryOptOut: z.boolean().optional(),
+  })
+  .strict();
+
 export const ManduConfigSchema = z
   .object({
     adapter: AdapterConfigSchema.optional(),
@@ -643,6 +685,13 @@ export const ManduConfigSchema = z
      * Optional; omission leaves i18n disabled with zero runtime overhead.
      */
     i18n: I18nConfigSchema.optional(),
+    /**
+     * Issue #235 — Brain adapter selection. See {@link BrainConfigSchema}.
+     * Optional; omission is equivalent to `{ adapter: "auto" }`, which
+     * resolves in priority order: openai-oauth → anthropic-oauth →
+     * ollama → template.
+     */
+    brain: BrainConfigSchema.optional(),
   })
   .strict();
 

package/src/runtime/server.ts

@@ -2848,6 +2848,9 @@ async function renderPageSSR(
         hmrPort: settings.hmrPort,
         routeId: route.id,
         routePattern: route.pattern,
+        // Issue #233 — emit data-mandu-layout so SPA nav can detect
+        // cross-layout transitions and hard-nav instead of half-swapping.
+        layoutChain: route.layoutChain,
         hydration: route.hydration,
         bundleManifest: settings.bundleManifest,
         criticalData: loaderData as Record<string, unknown> | undefined,
@@ -2896,6 +2899,9 @@ async function renderPageSSR(
       prefetch: settings.prefetch,
       spa: settings.spa,
       devtools: settings.devtools,
+      // Issue #233 — SPA nav uses this to detect cross-layout transitions
+      // and fall back to a hard navigation.
+      layoutChain: route.layoutChain,
     });
     return ok(cookies ? cookies.applyToResponse(ssrResponse) : ssrResponse);
   } catch (error) {

package/src/runtime/ssr.ts

@@ -53,6 +53,16 @@ export interface SSROptions {
   bundleManifest?: BundleManifest;
   /** 라우트 ID (island 식별용) */
   routeId?: string;
+  /**
+   * Issue #233 — layout chain applied to this render, ordered outer → inner.
+   * Serialized into `data-mandu-layout` on `<div id="root">` so the SPA
+   * navigation helper can detect cross-layout transitions and fall back
+   * to a hard navigation instead of a soft `<main>` swap (which would
+   * leave stale layout chrome like a sidebar from the source layout).
+   * When omitted or empty the attribute is dropped — same-layout nav
+   * remains cheap and visually crossfaded.
+   */
+  layoutChain?: string[];
   /** 추가 head 태그 */
   headTags?: string;
   /** 추가 body 끝 태그 */
@@ -623,8 +633,25 @@ export function renderToHTML(element: ReactElement, options: SSROptions = {}): s
     spa,
     devtools,
     devErrorOverlay,
+    layoutChain,
   } = options;
 
+  // Issue #233 — derive a stable short key for the layout chain so the
+  // SPA nav helper can detect cross-layout transitions. Deterministic
+  // per server, stable across the same route/layout combo. Missing /
+  // empty chain → omit the attribute entirely (attribute absence acts
+  // like a wildcard match).
+  let layoutKey = "";
+  if (layoutChain && layoutChain.length > 0) {
+    let hash = 0;
+    const joined = layoutChain.join("|");
+    for (let i = 0; i < joined.length; i++) {
+      hash = ((hash << 5) - hash + joined.charCodeAt(i)) | 0;
+    }
+    layoutKey = (hash >>> 0).toString(16).padStart(8, "0");
+  }
+  const rootAttrs = layoutKey ? ` data-mandu-layout="${layoutKey}"` : "";
+
   // CSS 링크 태그 생성
   // - cssPath가 string이면 해당 경로 사용
   // - cssPath가 false 또는 undefined이면 링크 미삽입 (404 방지)
@@ -804,7 +831,7 @@ export function renderToHTML(element: ReactElement, options: SSROptions = {}): s
   ${devErrorOverlayTag}
 </head>
 <body>
-  <div id="root">${bodyContent}</div>
+  <div id="root"${rootAttrs}>${bodyContent}</div>
   ${dataScript}
   ${routeScript}
   ${hydrationScripts}

package/src/runtime/streaming-ssr.ts

@@ -99,6 +99,12 @@ export interface StreamingSSROptions {
   routeId?: string;
   /** 라우트 패턴 */
   routePattern?: string;
+  /**
+   * Issue #233 — layout chain (outer → inner). Emitted as
+   * `data-mandu-layout="<hash>"` on `<div id="root">` so the SPA
+   * navigation helper can detect cross-layout transitions.
+   */
+  layoutChain?: string[];
   /** Critical 데이터 (Shell과 함께 즉시 전송) - JSON-serializable object만 허용 */
   criticalData?: Record<string, unknown>;
   // Note: deferredData는 renderWithDeferredData의 deferredPromises로 대체됨
@@ -543,8 +549,24 @@ function generateHTMLShell(options: StreamingSSROptions): string {
     transitions = true,
     prefetch = true,
     spa = true,
+    layoutChain,
   } = options;
 
+  // Issue #233 — layout-key for SPA cross-layout detection. Mirror of the
+  // block in `ssr.ts::renderToHTML`; see that call-site for the full
+  // rationale. Streaming path must stamp the same attribute so the SPA
+  // helper's layout-mismatch heuristic is consistent across modes.
+  let layoutKey = "";
+  if (layoutChain && layoutChain.length > 0) {
+    let hash = 0;
+    const joined = layoutChain.join("|");
+    for (let i = 0; i < joined.length; i++) {
+      hash = ((hash << 5) - hash + joined.charCodeAt(i)) | 0;
+    }
+    layoutKey = (hash >>> 0).toString(16).padStart(8, "0");
+  }
+  const rootAttrs = layoutKey ? ` data-mandu-layout="${layoutKey}"` : "";
+
   // CSS 링크 태그 생성
   // - cssPath가 string이면 해당 경로 사용
   // - cssPath가 false 또는 undefined이면 링크 미삽입 (404 방지)
@@ -652,7 +674,7 @@ function generateHTMLShell(options: StreamingSSROptions): string {
   ${fastRefreshPreamble}
 </head>
 <body>
-  <div id="root">${islandOpenTag}`;
+  <div id="root"${rootAttrs}>${islandOpenTag}`;
 }
 
 /**