@minjun0219/mdwire 0.1.6 → 0.1.8

package/README.md

@@ -9,8 +9,9 @@ escaping rules, and its own length limit. Existing converters assume the input i
 well-formed CommonMark and target one channel at a time. Neither assumption holds for
 agent output.
 
-**Status: v0.1.6.** Normalizing, rendering, splitting and streaming work for three
-channels — Telegram HTML, Slack `markdown_text`, and plain text — from a Rust core, a CLI,
+**Status: v0.1.8.** Normalizing, rendering, splitting and streaming work for five
+targets — Telegram HTML, Slack `markdown_text`, GitHub comments (GFM), plain text, and HTML for
+the browser — from a Rust core, a CLI,
 an npm package (WASM), and a Go port. See `SPEC.md` for what is in v0.1 and what was
 deliberately deferred. `SPEC.md` and `DESIGN.md` are written in Korean.
 
@@ -23,7 +24,14 @@ LLM markdown  →  normalize  →  render for channel  →  split safely  →  s
 1. **Normalize.** Agent output is not well-formed. Unpaired `**`, emphasis that spans a
    line break in wrapped prose, unclosed code fences. Repair before rendering.
 2. **Render.** Emit the syntax the channel actually accepts. Telegram HTML allows nine
-   tags; Slack `markdown_text` takes standard Markdown directly.
+   tags; Slack `markdown_text` takes standard Markdown directly. GitHub takes it too, but
+   reads a lone `~` as strikethrough and `<T>` as an HTML tag — so a `~` or `<` meant as a
+   character goes out escaped (`\~`, `\<`), and emphasis GFM would not close — `**(a)**`
+   followed directly by a Korean particle — goes out as `<strong>`. For the browser, `html` draws
+   blocks as tags too and is safe to set as `innerHTML`: text is escaped, inline tags from the
+   source keep no attributes, and only `http(s)`/`mailto` links become `<a>` — line breaks,
+   images and allowed schemes are options. While streaming,
+   the accumulated output plus `preview()` (or `closeOpen()`) is always balanced HTML.
 3. **Split.** Respect the channel's limit — and never cut through markup. This also
    covers streaming: a chunk boundary must not land inside `**bold**`.
 
@@ -38,6 +46,7 @@ markers — so you can log how often the model breaks its own formatting.
 ```sh
 cat agent-output.md | mdwire --channel telegram-html          # parts separated by NUL
 cat agent-output.md | mdwire --channel slack-markdown --stream # emit as it arrives
+cat agent-output.md | mdwire --channel plain --limit 4096      # plain fallback into Telegram
 
 # The agent wrote Slack's legacy mrkdwn (*bold*, ~strike~)? Say so. --report prints what
 # the normalizer fixed (unclosed emphasis, unclosed fence, …) as one JSON line on stderr.
@@ -58,17 +67,19 @@ import { render, renderWithReport, Streamer } from "@minjun0219/mdwire";   // np
 const parts = render(markdown, "telegram-html");
 const { repairs } = renderWithReport(markdown, "slack-markdown", { from: "slack-mrkdwn" });
 
-// A channel that rewrites the whole message (Telegram edit): send acc plus the tail
-// that closes open blocks. Keep acc itself untouched.
+// A channel that rewrites the whole message (Telegram edit): send acc plus the preview —
+// what is still held (open bold, table rows, a code span) drawn as if the input ended here.
+// Keep acc itself untouched. After finish, skip the last edit if nothing changed.
 const s = new Streamer("telegram-html");
 let acc = "";
 for await (const chunk of tokens) {
   acc += s.push(chunk);
-  await edit(acc + s.closeOpen());
+  await edit(acc + s.preview());
 }
 acc += s.finish();
+if (s.revised()) await edit(acc);
 
-// An append-only channel (Slack appendStream): send each piece as is — never closeOpen.
+// An append-only channel (Slack appendStream): send each piece as is — never preview.
 const t = new Streamer("slack-markdown");
 for await (const chunk of tokens) {
   const piece = t.push(chunk);
@@ -77,6 +88,25 @@ for await (const chunk of tokens) {
 await append(t.finish());
 ```
 
+In React, `@minjun0219/mdwire/react` builds elements with `createElement` — no
+`innerHTML`. Escaping, the tag set and link schemes are decided once, in the core's `html`
+channel; you choose which component draws each tag. `@minjun0219/mdwire/events` gives the
+same output as an `open` / `text` / `close` event list for other frameworks.
+
+```jsx
+import { Markdown, useMarkdownStream } from "@minjun0219/mdwire/react";
+
+<Markdown text={answer} components={{ a: RouterLink }} />  // a finished answer
+const { elements, push, finish } = useMarkdownStream();     // streaming: push(token), finish()
+```
+
+The hook draws held content early by default; `useMarkdownStream({ eager: false })` shows only
+what is final, and `onSettled(html, revised)` tells you whether the finished text differs from
+the last frame.
+
+[`examples/react-streaming`](examples/react-streaming) streams one answer into react-markdown, Streamdown,
+mdwire in front of Streamdown, and mdwire side by side. Measured numbers are in `DESIGN.md`.
+
 **Append-only contract.** What `push` returns is final — a later chunk never rewrites it —
 and `finish` only appends the tail. So the pieces concatenated equal a one-shot `render`,
 whatever the chunk size (unless the document is long enough to be split into parts).
@@ -128,11 +158,11 @@ Every release also carries its own artifacts, if you would rather not go through
 
 ```sh
 # npm package (works under a bundler and in plain Node)
-npm install https://github.com/minjun0219/mdwire/releases/download/v0.1.6/mdwire-0.1.6.tgz
+npm install https://github.com/minjun0219/mdwire/releases/download/v0.1.8/mdwire-0.1.8.tgz
 
 # CLI binary — macOS (Apple silicon) or Linux (x86_64)
-curl -L https://github.com/minjun0219/mdwire/releases/download/v0.1.6/mdwire-v0.1.6-aarch64-apple-darwin.tar.gz | tar xz
-curl -L https://github.com/minjun0219/mdwire/releases/download/v0.1.6/mdwire-v0.1.6-x86_64-unknown-linux-gnu.tar.gz | tar xz
+curl -L https://github.com/minjun0219/mdwire/releases/download/v0.1.8/mdwire-v0.1.8-aarch64-apple-darwin.tar.gz | tar xz
+curl -L https://github.com/minjun0219/mdwire/releases/download/v0.1.8/mdwire-v0.1.8-x86_64-unknown-linux-gnu.tar.gz | tar xz
 ```
 
 The release notes list a SHA-256 for every artifact — pin to it when installing by URL.

package/bundler/mdwire.d.ts

@@ -5,6 +5,17 @@
 export interface RenderOptions {
     /** 입력 표기. 슬랙 레거시 mrkdwn(`*굵게*` `~취소~`)으로 쓴 에이전트 출력이면 "slack-mrkdwn". */
     from?: "markdown" | "slack-mrkdwn";
+    /** 조각 한도(글자 수). 생략하면 채널의 한도다 — plain 을 텔레그램에 보내면 4096. 스트리밍은 나누지 않는다. */
+    limit?: number;
+    /** 브라우저 채널("html")의 정책. 기본값이 가장 보수적이다. */
+    html?: {
+        /** 블록 안 줄바꿈. "br"(기본) 은 `<br>`, "space" 는 브라우저가 공백으로 접게 둔다. */
+        lineBreaks?: "br" | "space";
+        /** 이미지. "link"(기본) 는 누르기 전에 아무것도 안 불러온다, "load" 는 `<img>`. */
+        images?: "link" | "load";
+        /** 링크·이미지 주소로 받는 스킴(콜론 없이). 주면 그것만 받는다. 기본 ["http","https","mailto"]. */
+        schemes?: string[];
+    };
 }
 
 
@@ -77,11 +88,28 @@ export class Streamer {
      */
     finish(): string;
     constructor(channel: string, options?: RenderOptions | null);
+    /**
+     * **지금 입력이 끝났다면 확정분 뒤에 붙을 꼬리.** `closeOpen` 과 같은 자리에 들어가지만
+     * 붙들고 있던 것(열린 강조, 표 행, 코드 스팬)까지 그린다. 누적본을 통째로 다시 그리는 쪽의
+     * 기본값이다. 추측이라 뒤 조각이 모양을 바꿀 수 있다 — 끝난 뒤 `revised()` 로 본다.
+     *
+     * ```js
+     * acc += s.push(chunk);
+     * await edit(acc + s.preview());      // 화면을 그릴 때만 부른다(열린 블록만큼 든다)
+     * acc += s.finish();
+     * if (s.revised()) await edit(acc);   // 마지막 화면이 곧 완성본이면 건너뛴다
+     * ```
+     */
+    preview(): string;
     push(chunk: string): string;
     /**
      * 지금까지 정규화가 고친 것. `finish` 뒤에 보면 문서 전체의 값이다.
      */
     repairs(): Repairs;
+    /**
+     * 완성본이 마지막 `preview()` 와 다른가 — `finish` 뒤에 본다.
+     */
+    revised(): boolean;
 }
 
 /**

package/bundler/mdwire_bg.js

@@ -217,6 +217,35 @@ export class Streamer {
             wasm.__wbindgen_add_to_stack_pointer(16);
         }
     }
+    /**
+     * **지금 입력이 끝났다면 확정분 뒤에 붙을 꼬리.** `closeOpen` 과 같은 자리에 들어가지만
+     * 붙들고 있던 것(열린 강조, 표 행, 코드 스팬)까지 그린다. 누적본을 통째로 다시 그리는 쪽의
+     * 기본값이다. 추측이라 뒤 조각이 모양을 바꿀 수 있다 — 끝난 뒤 `revised()` 로 본다.
+     *
+     * ```js
+     * acc += s.push(chunk);
+     * await edit(acc + s.preview());      // 화면을 그릴 때만 부른다(열린 블록만큼 든다)
+     * acc += s.finish();
+     * if (s.revised()) await edit(acc);   // 마지막 화면이 곧 완성본이면 건너뛴다
+     * ```
+     * @returns {string}
+     */
+    preview() {
+        let deferred1_0;
+        let deferred1_1;
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            wasm.streamer_preview(retptr, this.__wbg_ptr);
+            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+            deferred1_0 = r0;
+            deferred1_1 = r1;
+            return getStringFromWasm0(r0, r1);
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+            wasm.__wbindgen_export3(deferred1_0, deferred1_1, 1);
+        }
+    }
     /**
      * @param {string} chunk
      * @returns {string}
@@ -247,6 +276,14 @@ export class Streamer {
         const ret = wasm.streamer_repairs(this.__wbg_ptr);
         return Repairs.__wrap(ret);
     }
+    /**
+     * 완성본이 마지막 `preview()` 와 다른가 — `finish` 뒤에 본다.
+     * @returns {boolean}
+     */
+    revised() {
+        const ret = wasm.streamer_revised(this.__wbg_ptr);
+        return ret !== 0;
+    }
 }
 if (Symbol.dispose) Streamer.prototype[Symbol.dispose] = Streamer.prototype.free;
 
@@ -334,16 +371,54 @@ export function __wbg_Error_67e7344beaa85059(arg0, arg1) {
     const ret = Error(getStringFromWasm0(arg0, arg1));
     return addHeapObject(ret);
 }
+export function __wbg___wbindgen_string_get_92ab86bb19cbc12f(arg0, arg1) {
+    const obj = getObject(arg1);
+    const ret = typeof(obj) === 'string' ? obj : undefined;
+    var ptr1 = isLikeNone(ret) ? 0 : passStringToWasm0(ret, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+    var len1 = WASM_VECTOR_LEN;
+    getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
+    getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
+}
 export function __wbg___wbindgen_throw_5d9e815e6fdf150f(arg0, arg1) {
     throw new Error(getStringFromWasm0(arg0, arg1));
 }
-export function __wbg_from_16748d3d3d38a68a(arg0, arg1) {
+export function __wbg_from_5fbc1c43b212eab8(arg0, arg1) {
     const ret = getObject(arg1).from;
     var ptr1 = isLikeNone(ret) ? 0 : passStringToWasm0(ret, wasm.__wbindgen_export, wasm.__wbindgen_export2);
     var len1 = WASM_VECTOR_LEN;
     getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
     getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
 }
+export function __wbg_html_90d0c88b318a2996(arg0) {
+    const ret = getObject(arg0).html;
+    return isLikeNone(ret) ? 0 : addHeapObject(ret);
+}
+export function __wbg_images_61d0abc71a1a31d9(arg0, arg1) {
+    const ret = getObject(arg1).images;
+    var ptr1 = isLikeNone(ret) ? 0 : passStringToWasm0(ret, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+    var len1 = WASM_VECTOR_LEN;
+    getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
+    getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
+}
+export function __wbg_limit_04422401e3a1f949(arg0, arg1) {
+    const ret = getObject(arg1).limit;
+    getDataViewMemory0().setFloat64(arg0 + 8 * 1, isLikeNone(ret) ? 0 : ret, true);
+    getDataViewMemory0().setInt32(arg0 + 4 * 0, !isLikeNone(ret), true);
+}
+export function __wbg_lineBreaks_05a2d00e6ab123b1(arg0, arg1) {
+    const ret = getObject(arg1).lineBreaks;
+    var ptr1 = isLikeNone(ret) ? 0 : passStringToWasm0(ret, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+    var len1 = WASM_VECTOR_LEN;
+    getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
+    getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
+}
+export function __wbg_schemes_224d41c59d295a23(arg0, arg1) {
+    const ret = getObject(arg1).schemes;
+    var ptr1 = isLikeNone(ret) ? 0 : passArrayJsValueToWasm0(ret, wasm.__wbindgen_export);
+    var len1 = WASM_VECTOR_LEN;
+    getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
+    getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
+}
 export function __wbindgen_generic_0000000000000001(arg0, arg1) {
     // Cast intrinsic for `Ref(String) -> Externref`.
     const ret = getStringFromWasm0(arg0, arg1);
@@ -418,6 +493,16 @@ function isLikeNone(x) {
     return x === undefined || x === null;
 }
 
+function passArrayJsValueToWasm0(array, malloc) {
+    const ptr = malloc(array.length * 4, 4) >>> 0;
+    const mem = getDataViewMemory0();
+    for (let i = 0; i < array.length; i++) {
+        mem.setUint32(ptr + 4 * i, addHeapObject(array[i]), true);
+    }
+    WASM_VECTOR_LEN = array.length;
+    return ptr;
+}
+
 function passStringToWasm0(arg, malloc, realloc) {
     if (realloc === undefined) {
         const buf = cachedTextEncoder.encode(arg);

package/bundler/mdwire_bg.wasm.d.ts

@@ -20,8 +20,10 @@ export const rendered_repairs: (a: number) => number;
 export const streamer_closeOpen: (a: number, b: number) => void;
 export const streamer_finish: (a: number, b: number) => void;
 export const streamer_new: (a: number, b: number, c: number, d: number) => void;
+export const streamer_preview: (a: number, b: number) => void;
 export const streamer_push: (a: number, b: number, c: number, d: number) => void;
 export const streamer_repairs: (a: number) => number;
+export const streamer_revised: (a: number) => number;
 export const __wbindgen_export: (a: number, b: number) => number;
 export const __wbindgen_export2: (a: number, b: number, c: number, d: number) => number;
 export const __wbindgen_add_to_stack_pointer: (a: number) => number;

package/js/events.d.ts

@@ -0,0 +1,20 @@
+/** mdwire html 출력에 나오는 태그. */
+export type MdTag =
+  | "p" | "h1" | "h2" | "h3" | "h4" | "h5" | "h6" | "ul" | "ol" | "li" | "blockquote" | "pre" | "code"
+  | "strong" | "em" | "del" | "a" | "table" | "thead" | "tbody" | "tr" | "th" | "td" | "hr" | "br"
+  | "sub" | "sup" | "b" | "i" | "u" | "s" | "strike" | "span" | "small" | "mark" | "kbd" | "img";
+
+/**
+ * 이벤트 하나. 속성은 코어가 내는 것만 담긴다 —
+ * `a` 의 `href`, `code` 의 `class`(`language-…`), `th`·`td` 의 `style`(`text-align:…`), `ol` 의 `start`.
+ */
+export type MdEvent =
+  | { type: "open"; tag: MdTag; attrs: Record<string, string> }
+  | { type: "close"; tag: MdTag }
+  | { type: "void"; tag: "br" | "hr" }
+  /** 이미지는 `html.images: "load"` 일 때만 나온다. `src`·`alt` 를 담는다. */
+  | { type: "void"; tag: "img"; attrs: Record<string, string> }
+  | { type: "text"; text: string };
+
+/** html 채널 출력(또는 스트리밍 누적본 + `closeOpen()`)을 이벤트 배열로 푼다. */
+export function toEvents(html: string): MdEvent[];

package/js/events.js

@@ -0,0 +1,70 @@
+// mdwire 의 html 채널 출력을 이벤트 열로 푼다.
+//
+// **mdwire 가 낸 HTML 만 읽는다.** 코어가 글자를 전부 escape 하고 태그를 고정된 집합으로만
+// 내므로(SPEC 4절) 여기서 필요한 것은 작은 토크나이저 하나다. 남이 쓴 HTML 을 넣으면 모르는
+// 태그는 글자로 돌려준다 — 이 모듈은 새니타이저가 아니다. 안전 판단은 코어 한 곳에 있다.
+
+/** 출력에 나올 수 있는 태그. 이 밖의 것은 글자다. */
+const TAGS = new Set([
+  "p", "h1", "h2", "h3", "h4", "h5", "h6", "ul", "ol", "li", "blockquote", "pre", "code",
+  "strong", "em", "del", "a", "table", "thead", "tbody", "tr", "th", "td", "hr", "br",
+  "sub", "sup", "b", "i", "u", "s", "strike", "span", "small", "mark", "kbd", "img",
+]);
+const VOID = new Set(["br", "hr", "img"]);
+/** 태그마다 읽는 속성. 코어가 내는 것만 — 나머지는 버린다. */
+const ATTRS = { a: ["href"], code: ["class"], th: ["style"], td: ["style"], ol: ["start"], img: ["src", "alt"] };
+
+const ENTITIES = { amp: "&", lt: "<", gt: ">", quot: '"' };
+const decode = (s) => s.replace(/&(amp|lt|gt|quot);/g, (_, n) => ENTITIES[n]);
+
+/**
+ * html 채널 출력을 이벤트 배열로 바꾼다.
+ * @param {string} html `render(text, "html")` 의 결과, 또는 스트리밍 누적본 + `closeOpen()`.
+ * @returns {import("./events.d.ts").MdEvent[]}
+ */
+export function toEvents(html) {
+  const events = [];
+  let text = "";
+  const flush = () => {
+    if (text) {
+      events.push({ type: "text", text: decode(text) });
+      text = "";
+    }
+  };
+  let i = 0;
+  while (i < html.length) {
+    const lt = html.indexOf("<", i);
+    if (lt < 0) {
+      text += html.slice(i);
+      break;
+    }
+    text += html.slice(i, lt);
+    const gt = html.indexOf(">", lt);
+    const m = gt < 0 ? null : /^<(\/?)([a-z][a-z0-9]*)((?:\s+[a-z-]+="[^"]*")*)\s*\/?>$/.exec(html.slice(lt, gt + 1));
+    if (!m || !TAGS.has(m[2])) {
+      text += "<";
+      i = lt + 1;
+      continue;
+    }
+    flush();
+    const [, closing, tag, rawAttrs] = m;
+    if (closing) {
+      events.push({ type: "close", tag });
+    } else if (VOID.has(tag)) {
+      const attrs = {};
+      for (const [, name, value] of rawAttrs.matchAll(/([a-z-]+)="([^"]*)"/g)) {
+        if (ATTRS[tag]?.includes(name)) attrs[name] = decode(value);
+      }
+      events.push(tag === "img" ? { type: "void", tag, attrs } : { type: "void", tag });
+    } else {
+      const attrs = {};
+      for (const [, name, value] of rawAttrs.matchAll(/([a-z-]+)="([^"]*)"/g)) {
+        if (ATTRS[tag]?.includes(name)) attrs[name] = decode(value);
+      }
+      events.push({ type: "open", tag, attrs });
+    }
+    i = gt + 1;
+  }
+  flush();
+  return events;
+}

package/js/react.d.ts

@@ -0,0 +1,43 @@
+import type { ElementType, ReactElement, ReactNode } from "react";
+import type { MdTag } from "./events.js";
+import type { RenderOptions } from "@minjun0219/mdwire";
+
+/** 태그별로 갈아 끼울 컴포넌트 — 예: `{ a: MyLink, code: CodeBlock }`. 받는 props 는 그 태그의 것이다. */
+export type MdComponents = Partial<Record<MdTag, ElementType>>;
+
+export interface MarkdownProps {
+  /** 에이전트가 쓴 마크다운(완성된 글). 스트리밍은 `Streamer` + `toElements` 로 — 누적본을 매번 넘기면 처음부터 다시 변환한다. */
+  text: string;
+  /** 입력 표기. 슬랙 레거시 mrkdwn 이면 "slack-mrkdwn". */
+  from?: "markdown" | "slack-mrkdwn";
+  components?: MdComponents;
+  /** 코어에 넘길 옵션 — `html` 정책(줄바꿈·이미지·스킴)이 여기 든다. `from` 은 위 것이 이긴다. */
+  options?: RenderOptions;
+}
+
+/** 마크다운을 React 요소로 그린다. innerHTML 을 쓰지 않는다. */
+export function Markdown(props: MarkdownProps): ReactElement;
+
+export interface MarkdownStreamOptions {
+  from?: "markdown" | "slack-mrkdwn";
+  components?: MdComponents;
+  options?: RenderOptions;
+  /** 붙든 것(열린 강조·표 행·코드 스팬)도 먼저 그린다. 기본 `true`. `false` 면 확정된 것만. */
+  eager?: boolean;
+  /** 끝났을 때. `revised` 는 완성본이 마지막 화면과 다른가 — 거짓이면 훅은 다시 그리지 않는다. */
+  onSettled?: (html: string, revised: boolean) => void;
+}
+
+/**
+ * 스트리밍용 훅 — 토큰마다 `push`, 끝나면 `finish`. 기본은 붙든 것도 먼저 그린다(`eager`).
+ * `onSettled` 말고는 처음 한 번만 읽는다.
+ */
+export function useMarkdownStream(opts?: MarkdownStreamOptions): {
+  elements: ReactElement;
+  push(chunk: string): void;
+  finish(): void;
+};
+
+/** html 채널 출력(스트리밍이면 누적본 + `preview()` 또는 `closeOpen()`)을 React 노드로 바꾼다. */
+/** `schemes` 는 코어에 준 `options.html.schemes` 와 같게 준다. 기본 `["http", "https", "mailto"]`. */
+export function toElements(html: string, components?: MdComponents, schemes?: string[]): ReactNode[];

package/js/react.js

@@ -0,0 +1,154 @@
+// mdwire → React 요소. innerHTML 없이 createElement 로 조립한다.
+//
+// 안전 판단은 코어의 html 채널이 한다(글자 escape, 태그 고정, 링크 스킴). 여기서는 그 출력을
+// 이벤트로 풀어 요소로 세울 뿐이다 — 글자는 React 가 글자로 넣으니 다시 escape 할 것도 없다.
+// 링크·이미지 스킴만 한 번 더 본다: 소비자가 `a` 를 자기 컴포넌트로 갈아 끼워도 주소가 안전하도록.
+// 목록은 코어에 준 것(`options.html.schemes`)과 같다 — 다르면 코어가 허용한 링크를 여기서 막는다.
+import { createElement, Fragment, useCallback, useEffect, useReducer, useRef } from "react";
+import { render, Streamer } from "@minjun0219/mdwire";
+import { toEvents } from "./events.js";
+
+const DEFAULT_SCHEMES = ["http", "https", "mailto"];
+
+function allowed(url, schemes) {
+  const u = url.trimStart();
+  const colon = u.indexOf(":");
+  if (colon < 1) return false;
+  const scheme = u.slice(0, colon).toLowerCase();
+  return schemes.some((s) => s.toLowerCase() === scheme);
+}
+/** 이 안에서는 공백만 있는 글이 DOM 규칙상 자식이 될 수 없다(React 가 경고한다). */
+const NO_TEXT = new Set(["ul", "ol", "table", "thead", "tbody", "tr"]);
+
+function propsOf(tag, attrs, key, schemes) {
+  const props = { key };
+  if (tag === "a" && attrs.href && allowed(attrs.href, schemes)) props.href = attrs.href;
+  if (tag === "img" && attrs.src && allowed(attrs.src, schemes)) {
+    props.src = attrs.src;
+    props.alt = attrs.alt ?? "";
+  }
+  if (tag === "code" && attrs.class) props.className = attrs.class;
+  if ((tag === "th" || tag === "td") && attrs.style) {
+    const align = /^text-align:(left|right|center)$/.exec(attrs.style);
+    if (align) props.style = { textAlign: align[1] };
+  }
+  if (tag === "ol" && attrs.start) {
+    const n = Number(attrs.start);
+    if (Number.isInteger(n) && n > 0) props.start = n;
+  }
+  return props;
+}
+
+/**
+ * html 채널 출력을 React 노드 배열로 바꾼다. 스트리밍 누적본을 직접 다루는 쪽이 쓴다 —
+ * `toElements(acc + streamer.closeOpen())`.
+ * @param {string} html
+ * @param {Partial<Record<string, import("react").ElementType>>} [components] 태그별로 갈아 끼울 컴포넌트.
+ * @param {string[]} [schemes] 링크·이미지로 받는 스킴. 코어에 준 `options.html.schemes` 와 같게.
+ */
+export function toElements(html, components = {}, schemes = DEFAULT_SCHEMES) {
+  const root = { tag: null, children: [] };
+  const stack = [root];
+  let key = 0;
+  const make = (tag, attrs, children) =>
+    createElement(components[tag] ?? tag, propsOf(tag, attrs, key++, schemes), ...children);
+  for (const ev of toEvents(html)) {
+    const top = stack[stack.length - 1];
+    switch (ev.type) {
+      case "text":
+        if (!(NO_TEXT.has(top.tag) && ev.text.trim() === "")) top.children.push(ev.text);
+        break;
+      case "void":
+        // 주소가 안전하지 않은 이미지는 아예 세우지 않는다 — 빈 `<img>` 도 쓸모가 없다.
+        if (ev.tag === "img" && !allowed(ev.attrs?.src ?? "", schemes)) break;
+        top.children.push(make(ev.tag, ev.attrs ?? {}, []));
+        break;
+      case "open":
+        stack.push({ tag: ev.tag, attrs: ev.attrs, children: [] });
+        break;
+      case "close": {
+        // 코어 출력은 짝이 맞는다. 안 맞는 닫기는 버린다 — 남이 넣은 글이라도 트리는 선다.
+        if (top.tag !== ev.tag || stack.length === 1) break;
+        stack.pop();
+        stack[stack.length - 1].children.push(make(top.tag, top.attrs, top.children));
+        break;
+      }
+    }
+  }
+  // 안 닫힌 것은 닫는다(스트리밍 중 closeOpen 을 안 붙인 누적본).
+  while (stack.length > 1) {
+    const top = stack.pop();
+    stack[stack.length - 1].children.push(make(top.tag, top.attrs, top.children));
+  }
+  return root.children;
+}
+
+/**
+ * 에이전트 마크다운을 그린다 — 완성된 글용. 스트리밍 중인 누적본을 토큰마다 넘기면 매번
+ * 처음부터 다시 변환해 전체 비용이 제곱으로 늘고, 반쪽 마커(`**굵`, 여는 백틱, `##`)가 잠깐 글자로
+ * 보였다가 사라진다. 스트리밍은 [`useMarkdownStream`].
+ * @param {import("./react.d.ts").MarkdownProps} props
+ */
+export function Markdown({ text, from, components, options }) {
+  const opts = { ...options, ...(from ? { from } : {}) };
+  const html = render(text, "html", opts).join("");
+  return createElement(Fragment, null, ...toElements(html, components, opts.html?.schemes ?? DEFAULT_SCHEMES));
+}
+
+/**
+ * 스트리밍용 훅. 토큰이 오는 대로 `push(chunk)`, 끝나면 `finish()`.
+ *
+ * 기본(`eager: true`)은 **붙든 것도 먼저 그린다** — 열린 강조는 닫아서, 표는 지금까지 온 행으로,
+ * 코드 스팬은 닫아서(`Streamer.preview()`). 추측이라 뒤 토큰이 모양을 바꿀 수 있지만 완성본은
+ * 일괄 변환과 같다. `eager: false` 면 확정된 것만 보인다(append-only, SPEC 8.2) — 짝이 안 맞은
+ * 강조·판정 전 접두사는 확정될 때 나온다.
+ *
+ * 끝나면 `onSettled(html, revised)` — `revised` 는 완성본이 마지막으로 **화면에 그려진** 것과
+ * 다른가다. 같으면 훅은 다시 그리지 않는다.
+ * @param {import("./react.d.ts").MarkdownStreamOptions} [opts]
+ */
+export function useMarkdownStream({ from, components, options, eager = true, onSettled } = {}) {
+  const ref = useRef(null);
+  const init = useRef(null);
+  const [, rerender] = useReducer((n) => n + 1, 0);
+  if (init.current === null) {
+    const o = { ...options, ...(from ? { from } : {}) };
+    init.current = () => ({ streamer: new Streamer("html", o), acc: "", done: false, eager, schemes: o.html?.schemes ?? DEFAULT_SCHEMES });
+  }
+  // 해제됐으면 다시 만든다 — StrictMode 개발 모드는 이펙트를 붙였다 떼었다 다시 붙여서, 정리
+  // 함수가 스트리머를 먼저 해제한다(토큰이 오기 전이라 잃는 것은 없다).
+  const state = () => (ref.current ??= init.current());
+  state().onSettled = onSettled; // 콜백은 매번 최신 것을 본다
+  // wasm 메모리를 돌려준다 — 스트리머는 JS 가비지 컬렉터가 모르는 곳에 산다.
+  useEffect(
+    () => () => {
+      ref.current?.streamer.free();
+      ref.current = null;
+    },
+    [],
+  );
+  const push = useCallback((chunk) => {
+    const st = state();
+    if (st.done) return;
+    st.acc += st.streamer.push(chunk);
+    rerender();
+  }, []);
+  const finish = useCallback(() => {
+    const st = state();
+    if (st.done) return;
+    st.acc += st.streamer.finish();
+    st.done = true;
+    // 스트리머의 revised() 가 아니라 커밋된 화면과 비교한다. 렌더는 버려질 수 있어서(concurrent
+    // 렌더) 마지막으로 preview() 를 부른 렌더가 화면에 올라갔다는 보장이 없다.
+    const revised = st.acc !== st.shown;
+    st.onSettled?.(st.acc, revised);
+    if (revised) rerender();
+  }, []);
+  const st = state();
+  const tail = st.done ? "" : st.eager ? st.streamer.preview() : st.streamer.closeOpen();
+  const html = st.acc + tail;
+  useEffect(() => {
+    if (ref.current) ref.current.shown = html;
+  });
+  return { elements: createElement(Fragment, null, ...toElements(html, components, st.schemes)), push, finish };
+}

package/node/mdwire.d.ts

@@ -5,6 +5,17 @@
 export interface RenderOptions {
     /** 입력 표기. 슬랙 레거시 mrkdwn(`*굵게*` `~취소~`)으로 쓴 에이전트 출력이면 "slack-mrkdwn". */
     from?: "markdown" | "slack-mrkdwn";
+    /** 조각 한도(글자 수). 생략하면 채널의 한도다 — plain 을 텔레그램에 보내면 4096. 스트리밍은 나누지 않는다. */
+    limit?: number;
+    /** 브라우저 채널("html")의 정책. 기본값이 가장 보수적이다. */
+    html?: {
+        /** 블록 안 줄바꿈. "br"(기본) 은 `<br>`, "space" 는 브라우저가 공백으로 접게 둔다. */
+        lineBreaks?: "br" | "space";
+        /** 이미지. "link"(기본) 는 누르기 전에 아무것도 안 불러온다, "load" 는 `<img>`. */
+        images?: "link" | "load";
+        /** 링크·이미지 주소로 받는 스킴(콜론 없이). 주면 그것만 받는다. 기본 ["http","https","mailto"]. */
+        schemes?: string[];
+    };
 }
 
 
@@ -77,11 +88,28 @@ export class Streamer {
      */
     finish(): string;
     constructor(channel: string, options?: RenderOptions | null);
+    /**
+     * **지금 입력이 끝났다면 확정분 뒤에 붙을 꼬리.** `closeOpen` 과 같은 자리에 들어가지만
+     * 붙들고 있던 것(열린 강조, 표 행, 코드 스팬)까지 그린다. 누적본을 통째로 다시 그리는 쪽의
+     * 기본값이다. 추측이라 뒤 조각이 모양을 바꿀 수 있다 — 끝난 뒤 `revised()` 로 본다.
+     *
+     * ```js
+     * acc += s.push(chunk);
+     * await edit(acc + s.preview());      // 화면을 그릴 때만 부른다(열린 블록만큼 든다)
+     * acc += s.finish();
+     * if (s.revised()) await edit(acc);   // 마지막 화면이 곧 완성본이면 건너뛴다
+     * ```
+     */
+    preview(): string;
     push(chunk: string): string;
     /**
      * 지금까지 정규화가 고친 것. `finish` 뒤에 보면 문서 전체의 값이다.
      */
     repairs(): Repairs;
+    /**
+     * 완성본이 마지막 `preview()` 와 다른가 — `finish` 뒤에 본다.
+     */
+    revised(): boolean;
 }
 
 /**

package/node/mdwire.js

@@ -221,6 +221,35 @@ class Streamer {
             wasm.__wbindgen_add_to_stack_pointer(16);
         }
     }
+    /**
+     * **지금 입력이 끝났다면 확정분 뒤에 붙을 꼬리.** `closeOpen` 과 같은 자리에 들어가지만
+     * 붙들고 있던 것(열린 강조, 표 행, 코드 스팬)까지 그린다. 누적본을 통째로 다시 그리는 쪽의
+     * 기본값이다. 추측이라 뒤 조각이 모양을 바꿀 수 있다 — 끝난 뒤 `revised()` 로 본다.
+     *
+     * ```js
+     * acc += s.push(chunk);
+     * await edit(acc + s.preview());      // 화면을 그릴 때만 부른다(열린 블록만큼 든다)
+     * acc += s.finish();
+     * if (s.revised()) await edit(acc);   // 마지막 화면이 곧 완성본이면 건너뛴다
+     * ```
+     * @returns {string}
+     */
+    preview() {
+        let deferred1_0;
+        let deferred1_1;
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            wasm.streamer_preview(retptr, this.__wbg_ptr);
+            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+            deferred1_0 = r0;
+            deferred1_1 = r1;
+            return getStringFromWasm0(r0, r1);
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+            wasm.__wbindgen_export3(deferred1_0, deferred1_1, 1);
+        }
+    }
     /**
      * @param {string} chunk
      * @returns {string}
@@ -251,6 +280,14 @@ class Streamer {
         const ret = wasm.streamer_repairs(this.__wbg_ptr);
         return Repairs.__wrap(ret);
     }
+    /**
+     * 완성본이 마지막 `preview()` 와 다른가 — `finish` 뒤에 본다.
+     * @returns {boolean}
+     */
+    revised() {
+        const ret = wasm.streamer_revised(this.__wbg_ptr);
+        return ret !== 0;
+    }
 }
 if (Symbol.dispose) Streamer.prototype[Symbol.dispose] = Streamer.prototype.free;
 exports.Streamer = Streamer;
@@ -345,16 +382,54 @@ function __wbg_get_imports() {
             const ret = Error(getStringFromWasm0(arg0, arg1));
             return addHeapObject(ret);
         },
+        __wbg___wbindgen_string_get_92ab86bb19cbc12f: function(arg0, arg1) {
+            const obj = getObject(arg1);
+            const ret = typeof(obj) === 'string' ? obj : undefined;
+            var ptr1 = isLikeNone(ret) ? 0 : passStringToWasm0(ret, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+            var len1 = WASM_VECTOR_LEN;
+            getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
+            getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
+        },
         __wbg___wbindgen_throw_5d9e815e6fdf150f: function(arg0, arg1) {
             throw new Error(getStringFromWasm0(arg0, arg1));
         },
-        __wbg_from_16748d3d3d38a68a: function(arg0, arg1) {
+        __wbg_from_5fbc1c43b212eab8: function(arg0, arg1) {
             const ret = getObject(arg1).from;
             var ptr1 = isLikeNone(ret) ? 0 : passStringToWasm0(ret, wasm.__wbindgen_export, wasm.__wbindgen_export2);
             var len1 = WASM_VECTOR_LEN;
             getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
             getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
         },
+        __wbg_html_90d0c88b318a2996: function(arg0) {
+            const ret = getObject(arg0).html;
+            return isLikeNone(ret) ? 0 : addHeapObject(ret);
+        },
+        __wbg_images_61d0abc71a1a31d9: function(arg0, arg1) {
+            const ret = getObject(arg1).images;
+            var ptr1 = isLikeNone(ret) ? 0 : passStringToWasm0(ret, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+            var len1 = WASM_VECTOR_LEN;
+            getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
+            getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
+        },
+        __wbg_limit_04422401e3a1f949: function(arg0, arg1) {
+            const ret = getObject(arg1).limit;
+            getDataViewMemory0().setFloat64(arg0 + 8 * 1, isLikeNone(ret) ? 0 : ret, true);
+            getDataViewMemory0().setInt32(arg0 + 4 * 0, !isLikeNone(ret), true);
+        },
+        __wbg_lineBreaks_05a2d00e6ab123b1: function(arg0, arg1) {
+            const ret = getObject(arg1).lineBreaks;
+            var ptr1 = isLikeNone(ret) ? 0 : passStringToWasm0(ret, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+            var len1 = WASM_VECTOR_LEN;
+            getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
+            getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
+        },
+        __wbg_schemes_224d41c59d295a23: function(arg0, arg1) {
+            const ret = getObject(arg1).schemes;
+            var ptr1 = isLikeNone(ret) ? 0 : passArrayJsValueToWasm0(ret, wasm.__wbindgen_export);
+            var len1 = WASM_VECTOR_LEN;
+            getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
+            getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
+        },
         __wbindgen_generic_0000000000000001: function(arg0, arg1) {
             // Cast intrinsic for `Ref(String) -> Externref`.
             const ret = getStringFromWasm0(arg0, arg1);
@@ -436,6 +511,16 @@ function isLikeNone(x) {
     return x === undefined || x === null;
 }
 
+function passArrayJsValueToWasm0(array, malloc) {
+    const ptr = malloc(array.length * 4, 4) >>> 0;
+    const mem = getDataViewMemory0();
+    for (let i = 0; i < array.length; i++) {
+        mem.setUint32(ptr + 4 * i, addHeapObject(array[i]), true);
+    }
+    WASM_VECTOR_LEN = array.length;
+    return ptr;
+}
+
 function passStringToWasm0(arg, malloc, realloc) {
     if (realloc === undefined) {
         const buf = cachedTextEncoder.encode(arg);

package/node/mdwire_bg.wasm.d.ts

@@ -20,8 +20,10 @@ export const rendered_repairs: (a: number) => number;
 export const streamer_closeOpen: (a: number, b: number) => void;
 export const streamer_finish: (a: number, b: number) => void;
 export const streamer_new: (a: number, b: number, c: number, d: number) => void;
+export const streamer_preview: (a: number, b: number) => void;
 export const streamer_push: (a: number, b: number, c: number, d: number) => void;
 export const streamer_repairs: (a: number) => number;
+export const streamer_revised: (a: number) => number;
 export const __wbindgen_export: (a: number, b: number) => number;
 export const __wbindgen_export2: (a: number, b: number, c: number, d: number) => number;
 export const __wbindgen_add_to_stack_pointer: (a: number) => number;

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@minjun0219/mdwire",
-  "version": "0.1.6",
-  "description": "Streaming Markdown renderer for chat channels. Telegram HTML, Slack markdown_text, plain text.",
+  "version": "0.1.8",
+  "description": "Streaming Markdown renderer for chat channels and the browser. Telegram HTML, Slack markdown_text, GitHub, HTML, React.",
   "license": "MIT",
   "repository": { "type": "git", "url": "https://github.com/minjun0219/mdwire" },
   "homepage": "https://github.com/minjun0219/mdwire",
-  "keywords": ["markdown", "telegram", "slack", "streaming", "llm", "wasm"],
+  "keywords": ["markdown", "telegram", "slack", "github", "react", "streaming", "llm", "wasm"],
   "type": "module",
   "main": "./node/mdwire.js",
   "types": "./bundler/mdwire.d.ts",
@@ -14,9 +14,13 @@
       "types": "./bundler/mdwire.d.ts",
       "node": "./node/mdwire.js",
       "default": "./bundler/mdwire.js"
-    }
+    },
+    "./events": { "types": "./js/events.d.ts", "default": "./js/events.js" },
+    "./react": { "types": "./js/react.d.ts", "default": "./js/react.js" }
   },
+  "peerDependencies": { "react": ">=18" },
+  "peerDependenciesMeta": { "react": { "optional": true } },
   "sideEffects": ["./bundler/mdwire.js"],
-  "files": ["bundler", "node"],
+  "files": ["bundler", "node", "js"],
   "publishConfig": { "access": "public" }
 }