@minjun0219/mdwire 0.1.10 → 0.1.11

package/js/react.d.ts

@@ -2,32 +2,32 @@ import type { ElementType, ReactElement, ReactNode } from "react";
 import type { MdTag } from "./events.js";
 import type { RenderOptions } from "@minjun0219/mdwire";
 
-/** 태그별로 갈아 끼울 컴포넌트 — 예: `{ a: MyLink, code: CodeBlock }`. 받는 props 는 그 태그의 것이다. */
+/** Components that replace individual tags, e.g. `{ a: MyLink, code: CodeBlock }`. Each receives that tag's props. */
 export type MdComponents = Partial<Record<MdTag, ElementType>>;
 
 export interface MarkdownProps {
-  /** 에이전트가 쓴 마크다운(완성된 글). 스트리밍은 `Streamer` + `toElements` 로 — 누적본을 매번 넘기면 처음부터 다시 변환한다. */
+  /** Markdown written by the agent (complete text). For streaming, use `Streamer` + `toElements`; passing the accumulated output each time reconverts it from scratch. */
   text: string;
   components?: MdComponents;
-  /** 코어에 넘길 옵션 — `html` 정책(줄바꿈·이미지·스킴)이 여기 든다. */
+  /** Options passed to the core. The `html` policy (line breaks, images, schemes) goes here. */
   options?: RenderOptions;
 }
 
-/** 마크다운을 React 요소로 그린다. innerHTML 을 쓰지 않는다. */
+/** Renders markdown as React elements. Does not use innerHTML. */
 export function Markdown(props: MarkdownProps): ReactElement;
 
 export interface MarkdownStreamOptions {
   components?: MdComponents;
   options?: RenderOptions;
-  /** 붙든 것(열린 강조·표 행·코드 스팬)도 먼저 그린다. 기본 `true`. `false` 면 확정된 것만. */
+  /** Also draw what is held back (open emphasis, table rows, code spans) ahead of time. Default `true`. With `false`, only final output is shown. */
   eager?: boolean;
-  /** 끝났을 때. `revised` 는 완성본이 마지막 화면과 다른가 — 거짓이면 훅은 다시 그리지 않는다. */
+  /** Called when done. `revised` tells whether the final output differs from the last screen; if false, the hook does not redraw. */
   onSettled?: (html: string, revised: boolean) => void;
 }
 
 /**
- * 스트리밍용 훅 — 토큰마다 `push`, 끝나면 `finish`. 기본은 붙든 것도 먼저 그린다(`eager`).
- * `onSettled` 말고는 처음 한 번만 읽는다.
+ * Hook for streaming: call `push` for each token and `finish` at the end. By default it also draws what is held back (`eager`).
+ * Options other than `onSettled` are read only once, on first render.
  */
 export function useMarkdownStream(opts?: MarkdownStreamOptions): {
   elements: ReactElement;
@@ -35,6 +35,6 @@ export function useMarkdownStream(opts?: MarkdownStreamOptions): {
   finish(): void;
 };
 
-/** html 채널 출력(스트리밍이면 누적본 + `preview()` 또는 `closeOpen()`)을 React 노드로 바꾼다. */
-/** `schemes` 는 코어에 준 `options.html.schemes` 와 같게 준다. 기본 `["http", "https", "mailto"]`. */
+/** Converts html channel output (when streaming, the accumulated output + `preview()` or `closeOpen()`) into React nodes. */
+/** Pass the same `schemes` you gave the core as `options.html.schemes`. Default `["http", "https", "mailto"]`. */
 export function toElements(html: string, components?: MdComponents, schemes?: string[]): ReactNode[];

package/js/react.js

@@ -40,11 +40,11 @@ function propsOf(tag, attrs, key, schemes) {
 }
 
 /**
- * html 채널 출력을 React 노드 배열로 바꾼다. 스트리밍 누적본을 직접 다루는 쪽이 쓴다 —
- * `toElements(acc + streamer.closeOpen())`.
+ * Converts html channel output into an array of React nodes. Use it when you handle the
+ * accumulated stream output yourself: `toElements(acc + streamer.closeOpen())`.
  * @param {string} html
- * @param {Partial<Record<string, import("react").ElementType>>} [components] 태그별로 갈아 끼울 컴포넌트.
- * @param {string[]} [schemes] 링크·이미지로 받는 스킴. 코어에 준 `options.html.schemes` 와 같게.
+ * @param {Partial<Record<string, import("react").ElementType>>} [components] Components that replace individual tags.
+ * @param {string[]} [schemes] Schemes allowed for links and images. Same as the `options.html.schemes` given to the core.
  */
 export function toElements(html, components = {}, schemes = DEFAULT_SCHEMES) {
   const root = { tag: null, children: [] };
@@ -84,9 +84,9 @@ export function toElements(html, components = {}, schemes = DEFAULT_SCHEMES) {
 }
 
 /**
- * 에이전트 마크다운을 그린다 — 완성된 글용. 스트리밍 중인 누적본을 토큰마다 넘기면 매번
- * 처음부터 다시 변환해 전체 비용이 제곱으로 늘고, 반쪽 마커(`**굵`, 여는 백틱, `##`)가 잠깐 글자로
- * 보였다가 사라진다. 스트리밍은 [`useMarkdownStream`].
+ * Renders agent markdown, for complete text. If you pass the accumulated stream on every token,
+ * it reconverts from scratch each time, so total cost grows quadratically, and half-written markers
+ * (`**bo`, an opening backtick, `##`) briefly show up as text and then vanish. For streaming, use [`useMarkdownStream`].
  * @param {import("./react.d.ts").MarkdownProps} props
  */
 export function Markdown({ text, components, options }) {
@@ -95,15 +95,16 @@ export function Markdown({ text, components, options }) {
 }
 
 /**
- * 스트리밍용 훅. 토큰이 오는 대로 `push(chunk)`, 끝나면 `finish()`.
+ * Hook for streaming. Call `push(chunk)` as tokens arrive and `finish()` at the end.
  *
- * 기본(`eager: true`)은 **붙든 것도 먼저 그린다** — 열린 강조는 닫아서, 표는 지금까지 온 행으로,
- * 코드 스팬은 닫아서(`Streamer.preview()`). 추측이라 뒤 토큰이 모양을 바꿀 수 있지만 완성본은
- * 일괄 변환과 같다. `eager: false` 면 확정된 것만 보인다(append-only, SPEC 8.2) — 짝이 안 맞은
- * 강조·판정 전 접두사는 확정될 때 나온다.
+ * By default (`eager: true`) it **also draws what is held back**: open emphasis closed, tables with
+ * the rows received so far, code spans closed (`Streamer.preview()`). This is a guess, so later tokens
+ * may change the shape, but the final output matches a one-shot conversion. With `eager: false`, only
+ * final output is shown (append-only, SPEC 8.2): unmatched emphasis and prefixes not yet decided
+ * appear once they become final.
  *
- * 끝나면 `onSettled(html, revised)` — `revised` 는 완성본이 마지막으로 **화면에 그려진** 것과
- * 다른가다. 같으면 훅은 다시 그리지 않는다.
+ * At the end it calls `onSettled(html, revised)`. `revised` tells whether the final output differs
+ * from what was last **drawn on screen**. If they match, the hook does not redraw.
  * @param {import("./react.d.ts").MarkdownStreamOptions} [opts]
  */
 export function useMarkdownStream({ components, options, eager = true, onSettled } = {}) {

package/node/mdwire.d.ts

@@ -1,17 +1,17 @@
 /* tslint:disable */
 /* eslint-disable */
 
-/** 변환 옵션. 생략하면 채널의 기본값이다. */
+/** Conversion options. Anything omitted uses the channel's default. */
 export interface RenderOptions {
-    /** 조각 한도(글자 수). 생략하면 채널의 한도다 — plain 을 텔레그램에 보내면 4096. 스트리밍은 나누지 않는다. */
+    /** Part size limit (in characters). Defaults to the channel's limit; for example, 4096 when sending plain to Telegram. Streaming does not split. */
     limit?: number;
-    /** 브라우저 채널("html")의 정책. 기본값이 가장 보수적이다. */
+    /** Policy for the browser channel ("html"). The defaults are the most conservative. */
     html?: {
-        /** 블록 안 줄바꿈. "br"(기본) 은 `<br>`, "space" 는 브라우저가 공백으로 접게 둔다. */
+        /** Line breaks inside a block. "br" (default) emits `<br>`; "space" lets the browser collapse them into spaces. */
         lineBreaks?: "br" | "space";
-        /** 이미지. "link"(기본) 는 누르기 전에 아무것도 안 불러온다, "load" 는 `<img>`. */
+        /** Images. "link" (default) loads nothing until clicked; "load" emits `<img>`. */
         images?: "link" | "load";
-        /** 링크·이미지 주소로 받는 스킴(콜론 없이). 주면 그것만 받는다. 기본 ["http","https","mailto"]. */
+        /** Schemes allowed in link and image URLs (without the colon). If given, only these are allowed. Default ["http","https","mailto"]. */
         schemes?: string[];
     };
 }
@@ -19,133 +19,136 @@ export interface RenderOptions {
 
 
 /**
- * `renderWithReport` 의 결과.
+ * The result of `renderWithReport`.
  */
 export class Rendered {
     private constructor();
     free(): void;
     [Symbol.dispose](): void;
     /**
-     * 조각들. 한도를 넘지 않았으면 하나다.
+     * The parts. Just one if the text fit within the limit.
      */
     readonly parts: string[];
     /**
-     * 정규화가 고친 것.
+     * What normalization repaired.
      */
     readonly repairs: Repairs;
 }
 
 /**
- * 정규화가 고친 것과 채널에 맞춰 바꾼 것의 개수.
+ * Counts of what normalization repaired and what was changed to fit the channel.
  */
 export class Repairs {
     private constructor();
     free(): void;
     [Symbol.dispose](): void;
     /**
-     * 블록이 끝나도록 안 닫혀서 닫아 준 강조.
+     * Emphasis left open at the end of a block, closed for you.
      */
     closedEmphasis: number;
     /**
-     * 문서 끝까지 안 닫혀서 닫아 준 코드펜스.
+     * Code fences left open at the end of the document, closed for you.
      */
     closedFence: number;
     /**
-     * 다른 표기로 바꿔 쓴 강조 마커와 `<url|텍스트>` 링크.
+     * Emphasis markers and `<url|text>` links rewritten in a different notation.
      */
     convertedMarker: number;
     /**
-     * 짝 잃은 채 버린 `**`.
+     * Unmatched `**` markers that were dropped.
      */
     droppedMarker: number;
     /**
-     * 채널이 구문으로 읽을 글자를 이스케이프한 수(GitHub 의 `\~`·`\<`·`\*`).
+     * Characters escaped because the channel would read them as syntax (GitHub's `\~`, `\<`, `\*`).
      */
     escapedChar: number;
     /**
-     * 짝이 없어 글자로 되돌린 백틱 런.
+     * Unmatched backtick runs, turned back into literal text.
      */
     revertedCodeSpan: number;
     /**
-     * 다른 기호로 바꿔 쓴 목록 불릿.
+     * List bullets rewritten with a different symbol.
      */
     rewrittenBullet: number;
     /**
-     * 원문과 다른 모양으로 다시 쓴 표.
+     * Tables rewritten in a different shape from the source.
      */
     rewrittenTable: number;
     /**
-     * 벗긴 원문 HTML(태그·주석·줄바꿈으로 바꾼 `<br>`).
+     * Raw HTML stripped from the source (tags, comments, and `<br>` turned into line breaks).
      */
     strippedHtml: number;
     /**
-     * 채널이 마커로 못 읽는 자리라 다르게 낸 강조(GitHub 의 `<strong>`, 슬랙의 U+2060).
+     * Emphasis emitted differently because the channel would not read the marker in that position (GitHub's `<strong>`, Slack's U+2060).
      */
     tagEmphasis: number;
 }
 
 /**
- * 스트리밍 변환기.
+ * Streaming converter.
  *
- * 조각을 넣으면 지금 안전하게 내보낼 수 있는 만큼만 돌려준다. 경계에 걸린 마크업은
- * 안에 남는다 — 토큰이 흘러들어오는 대로 화면에 붙이는 쪽이 이것 때문에 쓴다.
+ * Push a chunk and it returns only what is safe to emit now. Markup cut off at the
+ * chunk boundary stays inside. This is what you want when appending tokens to the
+ * screen as they arrive.
  */
 export class Streamer {
     free(): void;
     [Symbol.dispose](): void;
     /**
-     * **지금까지 받은 것을 그대로 보내려면 이걸 뒤에 붙인다.**
+     * **To send what you have received so far as is, append this after it.**
      *
-     * 상태는 건드리지 않으므로 붙인 뒤에도 스트리밍은 이어진다. 누적본 자체에는
-     * 넣지 말고, 보내기 직전에만 붙인다. 토큰이 오는 대로 메시지를 편집하는 쪽이 쓴다.
+     * It does not touch the state, so streaming continues afterwards. Do not add it
+     * to the accumulated output itself; append it only right before sending. Use it
+     * when editing a message as tokens arrive.
      *
      * ```js
      * acc += s.push(chunk);
-     * await edit(acc + s.closeOpen());   // 누적본은 그대로 둔다
+     * await edit(acc + s.closeOpen());   // leave acc unchanged
      * ```
      */
     closeOpen(): string;
     /**
-     * 입력이 끝났다. 남은 것을 내보내고 열린 마크업을 닫는다.
+     * Input has ended. Emits what is left and closes open markup.
      */
     finish(): string;
     constructor(channel: string, options?: RenderOptions | null);
     /**
-     * **지금 입력이 끝났다면 확정분 뒤에 붙을 꼬리.** `closeOpen` 과 같은 자리에 들어가지만
-     * 붙들고 있던 것(열린 강조, 표 행, 코드 스팬)까지 그린다. 누적본을 통째로 다시 그리는 쪽의
-     * 기본값이다. 추측이라 뒤 조각이 모양을 바꿀 수 있다 — 끝난 뒤 `revised()` 로 본다.
+     * **The tail that would follow the final output if input ended now.** It goes in the
+     * same place as `closeOpen`, but also draws what is being held back (open emphasis,
+     * table rows, code spans). This is the default when you redraw the whole message.
+     * It is a guess, so later chunks may change the shape. Check `revised()` after the end.
      *
      * ```js
      * acc += s.push(chunk);
-     * await edit(acc + s.preview());      // 화면을 그릴 때만 부른다(열린 블록만큼 든다)
+     * await edit(acc + s.preview());      // call only when drawing (costs as much as the open block)
      * acc += s.finish();
-     * if (s.revised()) await edit(acc);   // 마지막 화면이 곧 완성본이면 건너뛴다
+     * if (s.revised()) await edit(acc);   // skip if the last screen already is the final output
      * ```
      */
     preview(): string;
     push(chunk: string): string;
     /**
-     * 지금까지 정규화가 고친 것. `finish` 뒤에 보면 문서 전체의 값이다.
+     * What normalization has repaired so far. After `finish`, this covers the whole document.
      */
     repairs(): Repairs;
     /**
-     * 완성본이 마지막 `preview()` 와 다른가 — `finish` 뒤에 본다.
+     * Whether the final output differs from the last `preview()`. Check it after `finish`.
      */
     revised(): boolean;
 }
 
 /**
- * 채널의 길이 한도(문자 수). 조각을 직접 다루려는 호출자를 위해 열어 둔다.
+ * The channel's length limit (in characters). Exposed for callers that handle parts themselves.
  */
 export function limit(channel: string): number;
 
 /**
- * 완성된 문서를 변환한다. 한도를 넘으면 조각 배열로 돌아온다.
+ * Converts a complete document. Returns an array of parts; it has more than one when the text exceeds the limit.
  */
 export function render(input: string, channel: string, options?: RenderOptions | null): string[];
 
 /**
- * [`render`] 에 **정규화가 고친 것**을 같이 돌려준다. 모델이 얼마나 자주 서식을 깨는지
- * 로그로 남기려는 쪽이 쓴다.
+ * Like [`render`], but also returns **what normalization repaired**. Use it to log
+ * how often the model breaks formatting.
  */
 export function renderWithReport(input: string, channel: string, options?: RenderOptions | null): Rendered;