@mandujs/core 0.19.0 → 0.19.2

package/src/client/use-sse.ts

@@ -0,0 +1,378 @@
+/**
+ * Mandu useSSE Hook - ReadableStream SSE reading for island components
+ *
+ * Problem: When a React component (inside createRoot) reads a ReadableStream
+ * in a tight `while(true) { await reader.read(); setState(...); }` loop,
+ * React 19's internal scheduler uses `queueMicrotask` to process state updates.
+ * Combined with fast SSE token streams, the microtask queue never drains,
+ * starving the macrotask queue (DOM painting, user input, MessageChannel).
+ * This effectively freezes the main thread.
+ *
+ * Solution: This hook yields to the macrotask queue between chunks using
+ * `setTimeout(0)`, allowing the browser to paint and process user input
+ * between state updates. Chunks arriving during the yield are coalesced
+ * into a single state update to minimize re-renders.
+ *
+ * @module client/use-sse
+ */
+
+import { useState, useCallback, useRef, useEffect } from "react";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface UseSSEOptions {
+  /**
+   * Called for each SSE chunk (after TextDecoder).
+   * Return the new accumulated value to set as state.
+   * @param accumulated - Current accumulated value
+   * @param chunk - New text chunk from the stream
+   * @returns Updated accumulated value
+   */
+  onChunk?: (accumulated: string, chunk: string) => string;
+
+  /**
+   * Called when the stream completes.
+   * @param finalValue - The final accumulated value
+   */
+  onComplete?: (finalValue: string) => void;
+
+  /**
+   * Called when the stream errors.
+   * @param error - The error that occurred
+   */
+  onError?: (error: Error) => void;
+
+  /**
+   * Minimum interval between state updates in ms.
+   * Higher values reduce re-renders but increase perceived latency.
+   * Default: 0 (yield once per chunk via setTimeout(0))
+   */
+  throttleMs?: number;
+}
+
+export interface UseSSEReturn {
+  /** Current accumulated stream data */
+  data: string;
+
+  /** Whether the stream is currently active */
+  isStreaming: boolean;
+
+  /** Error if the stream failed */
+  error: Error | null;
+
+  /**
+   * Start reading an SSE stream.
+   * Pass a fetch Response or a ReadableStream<Uint8Array>.
+   */
+  start: (source: Response | ReadableStream<Uint8Array>) => void;
+
+  /**
+   * Abort the current stream.
+   */
+  abort: () => void;
+
+  /** Reset state (data, error, isStreaming) */
+  reset: () => void;
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+/**
+ * Yield to the macrotask queue, allowing the browser to paint and
+ * process user input. This breaks the microtask starvation cycle
+ * caused by tight `await reader.read()` + `setState()` loops.
+ */
+function yieldToMacrotask(): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, 0));
+}
+
+// ============================================================================
+// Hook
+// ============================================================================
+
+/**
+ * React hook for reading SSE / ReadableStream data inside island components
+ * without blocking the main thread.
+ *
+ * @example
+ * ```tsx
+ * import { useSSE } from "@mandujs/core/client";
+ *
+ * function ChatIsland() {
+ *   const { data, isStreaming, start } = useSSE({
+ *     onComplete: (text) => console.log("Done:", text),
+ *   });
+ *
+ *   const sendMessage = async () => {
+ *     const res = await fetch("/api/chat", { method: "POST", body: ... });
+ *     start(res);
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       <p>{data}</p>
+ *       {isStreaming && <span>streaming...</span>}
+ *       <button onClick={sendMessage} disabled={isStreaming}>Send</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useSSE(options: UseSSEOptions = {}): UseSSEReturn {
+  const {
+    onChunk = (acc: string, chunk: string) => acc + chunk,
+    onComplete,
+    onError,
+    throttleMs = 0,
+  } = options;
+
+  const [data, setData] = useState("");
+  const [isStreaming, setIsStreaming] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  // Refs for the current stream session (allow abort & prevent stale closures)
+  const abortRef = useRef<AbortController | null>(null);
+  const accumulatorRef = useRef("");
+  const pendingChunksRef = useRef("");
+  const flushScheduledRef = useRef(false);
+  const optionsRef = useRef({ onChunk, onComplete, onError, throttleMs });
+
+  // Keep options ref in sync
+  useEffect(() => {
+    optionsRef.current = { onChunk, onComplete, onError, throttleMs };
+  });
+
+  // Cleanup on unmount
+  useEffect(() => {
+    return () => {
+      if (abortRef.current) {
+        abortRef.current.abort();
+        abortRef.current = null;
+      }
+    };
+  }, []);
+
+  /**
+   * Flush pending chunks as a single batched state update.
+   * Uses setTimeout(0) to yield to the macrotask queue first.
+   */
+  const flushPending = useCallback(() => {
+    if (!flushScheduledRef.current) return;
+
+    const pending = pendingChunksRef.current;
+    if (pending) {
+      const { onChunk: chunkFn } = optionsRef.current;
+      accumulatorRef.current = chunkFn(accumulatorRef.current, pending);
+      pendingChunksRef.current = "";
+      setData(accumulatorRef.current);
+    }
+    flushScheduledRef.current = false;
+  }, []);
+
+  /**
+   * Schedule a flush via setTimeout to yield to macrotask queue.
+   */
+  const scheduleFlush = useCallback(() => {
+    if (!flushScheduledRef.current) {
+      flushScheduledRef.current = true;
+      setTimeout(flushPending, optionsRef.current.throttleMs);
+    }
+  }, [flushPending]);
+
+  const start = useCallback(
+    (source: Response | ReadableStream<Uint8Array>) => {
+      // Abort any existing stream
+      if (abortRef.current) {
+        abortRef.current.abort();
+      }
+
+      const controller = new AbortController();
+      abortRef.current = controller;
+      accumulatorRef.current = "";
+      pendingChunksRef.current = "";
+      flushScheduledRef.current = false;
+
+      setData("");
+      setError(null);
+      setIsStreaming(true);
+
+      const body =
+        source instanceof Response ? source.body : source;
+
+      if (!body) {
+        setIsStreaming(false);
+        setError(new Error("Response has no body"));
+        return;
+      }
+
+      // Start reading in a properly-yielding async loop
+      (async () => {
+        const reader = body.getReader();
+        const decoder = new TextDecoder();
+
+        try {
+          while (true) {
+            // Check for abort
+            if (controller.signal.aborted) {
+              reader.cancel();
+              break;
+            }
+
+            const { done, value } = await reader.read();
+            if (done) break;
+
+            // Check for abort again (may have been aborted during read)
+            if (controller.signal.aborted) {
+              reader.cancel();
+              break;
+            }
+
+            const text = decoder.decode(value, { stream: true });
+            if (text) {
+              // Accumulate chunks and schedule a batched flush
+              pendingChunksRef.current += text;
+              scheduleFlush();
+            }
+
+            // CRITICAL: Yield to the macrotask queue to prevent microtask
+            // starvation. Without this, the tight loop of
+            // `await reader.read() -> setState -> React microtask -> next read`
+            // starves the browser's macrotask queue, freezing the UI.
+            await yieldToMacrotask();
+          }
+
+          // Final flush for any remaining chunks
+          if (pendingChunksRef.current) {
+            flushScheduledRef.current = true;
+            flushPending();
+          }
+
+          if (!controller.signal.aborted) {
+            setIsStreaming(false);
+            const opts = optionsRef.current;
+            if (opts.onComplete) {
+              opts.onComplete(accumulatorRef.current);
+            }
+          }
+        } catch (err) {
+          if (
+            !controller.signal.aborted &&
+            !(err instanceof DOMException && err.name === "AbortError")
+          ) {
+            const error =
+              err instanceof Error ? err : new Error(String(err));
+            setError(error);
+            setIsStreaming(false);
+            const opts = optionsRef.current;
+            if (opts.onError) {
+              opts.onError(error);
+            }
+          }
+        }
+      })();
+    },
+    [scheduleFlush, flushPending]
+  );
+
+  const abort = useCallback(() => {
+    if (abortRef.current) {
+      abortRef.current.abort();
+      abortRef.current = null;
+    }
+    setIsStreaming(false);
+  }, []);
+
+  const reset = useCallback(() => {
+    abort();
+    setData("");
+    setError(null);
+    accumulatorRef.current = "";
+    pendingChunksRef.current = "";
+    flushScheduledRef.current = false;
+  }, [abort]);
+
+  return { data, isStreaming, error, start, abort, reset };
+}
+
+// ============================================================================
+// Low-level utility (for non-hook usage)
+// ============================================================================
+
+/**
+ * Read a ReadableStream with macrotask yielding, suitable for use
+ * outside of React components (e.g., in plain event handlers).
+ *
+ * @example
+ * ```ts
+ * import { readStreamWithYield } from "@mandujs/core/client";
+ *
+ * const response = await fetch("/api/stream");
+ * await readStreamWithYield(response.body!, {
+ *   onChunk: (text) => {
+ *     // update DOM directly
+ *     el.textContent += text;
+ *   },
+ *   onDone: () => console.log("done"),
+ * });
+ * ```
+ */
+export interface ReadStreamOptions {
+  /** Called for each decoded text chunk */
+  onChunk: (text: string) => void;
+  /** Called when the stream is complete */
+  onDone?: () => void;
+  /** Called on error */
+  onError?: (error: Error) => void;
+  /** AbortSignal to cancel reading */
+  signal?: AbortSignal;
+}
+
+export async function readStreamWithYield(
+  stream: ReadableStream<Uint8Array>,
+  options: ReadStreamOptions
+): Promise<void> {
+  const { onChunk, onDone, onError, signal } = options;
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+
+  try {
+    while (true) {
+      if (signal?.aborted) {
+        reader.cancel();
+        break;
+      }
+
+      const { done, value } = await reader.read();
+      if (done) break;
+
+      if (signal?.aborted) {
+        reader.cancel();
+        break;
+      }
+
+      const text = decoder.decode(value, { stream: true });
+      if (text) {
+        onChunk(text);
+      }
+
+      // Yield to macrotask queue
+      await yieldToMacrotask();
+    }
+
+    if (!signal?.aborted) {
+      onDone?.();
+    }
+  } catch (err) {
+    if (
+      !signal?.aborted &&
+      !(err instanceof DOMException && err.name === "AbortError")
+    ) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      onError?.(error);
+    }
+  }
+}

package/src/components/Image.tsx

@@ -0,0 +1,162 @@
+/**
+ * Mandu <Image> Component
+ * 서버 사이드 이미지 최적화 — srcset, lazy loading, LCP preload
+ */
+
+import React from "react";
+
+// ========== Types ==========
+
+export interface ImageProps extends Omit<React.ImgHTMLAttributes<HTMLImageElement>, "src" | "srcSet"> {
+  /** 이미지 소스 경로 (/public 기준) */
+  src: string;
+  /** alt 텍스트 (필수 — 접근성) */
+  alt: string;
+  /** 너비 (px) */
+  width: number;
+  /** 높이 (px) */
+  height: number;
+  /** 반응형 sizes 속성 */
+  sizes?: string;
+  /** LCP 이미지 — preload 힌트 삽입 (기본: false) */
+  priority?: boolean;
+  /** 이미지 품질 (1-100, 기본: 80) */
+  quality?: number;
+  /** 플레이스홀더 (기본: "empty") */
+  placeholder?: "empty" | "blur";
+  /** 생성할 srcset 너비 목록 (기본: [640, 750, 828, 1080, 1200]) */
+  widths?: number[];
+}
+
+// ========== Constants ==========
+
+const DEFAULT_WIDTHS = [640, 750, 828, 1080, 1200];
+const IMAGE_HANDLER_PATH = "/_mandu/image";
+
+// ========== Helper ==========
+
+function buildImageUrl(src: string, width: number, quality: number): string {
+  return `${IMAGE_HANDLER_PATH}?url=${encodeURIComponent(src)}&w=${width}&q=${quality}`;
+}
+
+function buildSrcSet(src: string, widths: number[], quality: number): string {
+  return widths
+    .map(w => `${buildImageUrl(src, w, quality)} ${w}w`)
+    .join(", ");
+}
+
+// ========== Component ==========
+
+/**
+ * 최적화된 이미지 컴포넌트
+ *
+ * @example
+ * ```tsx
+ * import { Image } from "@mandujs/core/components/Image";
+ *
+ * <Image
+ *   src="/photos/hero.jpg"
+ *   alt="Hero"
+ *   width={800}
+ *   height={400}
+ *   sizes="(max-width: 768px) 100vw, 800px"
+ *   priority
+ * />
+ * ```
+ */
+export function Image({
+  src,
+  alt,
+  width,
+  height,
+  sizes,
+  priority = false,
+  quality = 80,
+  placeholder = "empty",
+  widths = DEFAULT_WIDTHS,
+  style,
+  ...rest
+}: ImageProps) {
+  const optimizedSrc = buildImageUrl(src, width, quality);
+  const srcSet = buildSrcSet(src, widths, quality);
+  const blurPlaceholderSrc = buildImageUrl(src, Math.min(width, 32), Math.max(10, Math.min(quality, 30)));
+
+  const imgStyle: React.CSSProperties = {
+    display: "block",
+    aspectRatio: `${width}/${height}`,
+    maxWidth: "100%",
+    height: "auto",
+    position: placeholder === "blur" ? "relative" : undefined,
+    zIndex: placeholder === "blur" ? 1 : undefined,
+    ...style,
+  };
+
+  const wrapperStyle: React.CSSProperties | undefined = placeholder === "blur"
+    ? {
+        position: "relative",
+        display: "inline-block",
+        overflow: "hidden",
+        maxWidth: "100%",
+      }
+    : undefined;
+
+  const blurPlaceholderStyle: React.CSSProperties | undefined = placeholder === "blur"
+    ? {
+        position: "absolute",
+        inset: 0,
+        backgroundImage: `url("${blurPlaceholderSrc}")`,
+        backgroundSize: "cover",
+        backgroundPosition: "center",
+        filter: "blur(16px)",
+        transform: "scale(1.05)",
+      }
+    : undefined;
+
+  return (
+    <>
+      {/* React 19: <link> 자동 <head> 호이스팅 지원 */}
+      {priority && (
+        React.createElement("link", {
+          rel: "preload",
+          as: "image",
+          href: optimizedSrc,
+          imageSrcSet: srcSet,
+          imageSizes: sizes,
+          fetchPriority: "high",
+        })
+      )}
+      {placeholder === "blur" ? (
+        <span style={wrapperStyle}>
+          <span aria-hidden="true" style={blurPlaceholderStyle} />
+          <img
+            src={optimizedSrc}
+            srcSet={srcSet}
+            sizes={sizes ?? `${width}px`}
+            alt={alt}
+            width={width}
+            height={height}
+            loading={priority ? "eager" : "lazy"}
+            decoding={priority ? "sync" : "async"}
+            fetchPriority={priority ? "high" : undefined}
+            style={imgStyle}
+            {...rest}
+          />
+        </span>
+      ) : (
+        <img
+          src={optimizedSrc}
+          srcSet={srcSet}
+          sizes={sizes ?? `${width}px`}
+          alt={alt}
+          width={width}
+          height={height}
+          loading={priority ? "eager" : "lazy"}
+          decoding={priority ? "sync" : "async"}
+          fetchPriority={priority ? "high" : undefined}
+          style={imgStyle}
+          {...rest}
+        />
+      )}
+    </>
+  );
+}

package/src/config/mandu.ts

@@ -1,9 +1,12 @@
 import path from "path";
 import { readJsonFile } from "../utils/bun";
+import type { ManduAdapter } from "../runtime/adapter";
+import type { ManduPlugin, ManduHooks } from "../plugins/hooks";
 
 export type GuardRuleSeverity = "error" | "warn" | "warning" | "off";
 
 export interface ManduConfig {
+  adapter?: ManduAdapter;
   server?: {
     port?: number;
     hostname?: string;
@@ -54,6 +57,8 @@ export interface ManduConfig {
     defaultTitle?: string;
     titleTemplate?: string;
   };
+  plugins?: ManduPlugin[];
+  hooks?: Partial<ManduHooks>;
 }
 
 export const CONFIG_FILES = [

package/src/config/validate.ts

@@ -3,6 +3,8 @@ import path from "path";
 import { pathToFileURL } from "url";
 import { CONFIG_FILES, coerceConfig } from "./mandu";
 import { readJsonFile } from "../utils/bun";
+import type { ManduAdapter } from "../runtime/adapter";
+import type { ManduPlugin, ManduHooks } from "../plugins/hooks";
 
 /**
  * DNA-003: Strict mode schema helper
@@ -124,20 +126,52 @@ const SeoConfigSchema = z
   })
   .strict();
 
+const AdapterConfigSchema = z.custom<ManduAdapter | undefined>(
+  (value) =>
+    value === undefined ||
+    (typeof value === "object" &&
+      value !== null &&
+      typeof (value as { name?: unknown }).name === "string" &&
+      typeof (value as { createServer?: unknown }).createServer === "function"),
+  {
+    message: "adapter must be a ManduAdapter with name and createServer()",
+  }
+);
+
 /**
  * Mandu 설정 스키마 (DNA-003: strict mode)
  *
  * 알 수 없는 키가 있으면 오류 발생 → 오타 즉시 감지
  * MANDU_STRICT=0 으로 비활성화 가능
  */
+/**
+ * Plugin schema — array of objects with `name` (string) and optional `hooks`/`setup`.
+ * Validated structurally; hook functions are opaque to Zod.
+ */
+const ManduPluginSchema = z.custom<ManduPlugin>(
+  (v) =>
+    typeof v === "object" &&
+    v !== null &&
+    typeof (v as { name?: unknown }).name === "string",
+  { message: "Each plugin must be an object with a `name` string" }
+);
+
+const ManduHooksSchema = z.custom<Partial<ManduHooks>>(
+  (v) => typeof v === "object" && v !== null,
+  { message: "hooks must be an object" }
+);
+
 export const ManduConfigSchema = z
   .object({
+    adapter: AdapterConfigSchema.optional(),
     server: ServerConfigSchema.default({}),
     guard: GuardConfigSchema.default({}),
     build: BuildConfigSchema.default({}),
     dev: DevConfigSchema.default({}),
     fsRoutes: FsRoutesConfigSchema.default({}),
     seo: SeoConfigSchema.default({}),
+    plugins: z.array(ManduPluginSchema).optional(),
+    hooks: ManduHooksSchema.optional(),
   })
   .strict();
 

package/src/content/index.ts

@@ -157,8 +157,12 @@ export {
  * });
  * ```
  */
-import type { ContentConfig as ContentConfigType } from "./types";
+import type { CollectionConfig, ContentConfig as ContentConfigType } from "./types";
 
 export function defineContentConfig<T extends ContentConfigType>(config: T): T {
   return config;
 }
+
+export function defineCollection<T extends CollectionConfig>(config: T): T {
+  return config;
+}

package/src/devtools/client/catchers/error-catcher.ts

@@ -254,6 +254,23 @@ export class ErrorCatcher {
 
     const hook = getOrCreateHook();
     hook.emit(createErrorEvent(error));
+
+    // Kitchen → MCP bridge: POST error to dev server for MCP tool access
+    this.reportToServer(error);
+  }
+
+  private reportToServer(error: NormalizedError): void {
+    try {
+      fetch("/__kitchen/api/errors", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(error),
+      }).catch(() => {
+        // Silently fail — dev server may not be running
+      });
+    } catch {
+      // Ignore
+    }
   }
 
   // --------------------------------------------------------------------------