@minjun0219/mdwire 0.1.9 → 0.1.11

package/README.md

@@ -5,12 +5,12 @@ English | [한국어](README.ko.md)
 Send LLM-generated Markdown to chat channels without it breaking.
 Docs, API reference and a live demo: [mdwire.minjun.dev](https://mdwire.minjun.dev).
 
-Agents emit Markdown. Chat channels don't accept it — each has its own subset, its own
+Agents emit Markdown. Chat channels don't take it as is — each has its own subset, its own
 escaping rules, and its own length limit. Existing converters assume the input is
 well-formed CommonMark and target one channel at a time. Neither assumption holds for
 agent output.
 
-**Status: v0.1.9.** Normalizing, rendering, splitting and streaming work for six
+**Status: v0.1.11.** Normalizing, rendering, splitting and streaming work for six
 targets — Telegram HTML, Slack `markdown_text`, GitHub comments (GFM), Notion pages, 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
@@ -22,15 +22,16 @@ deliberately deferred. `SPEC.md` and `DESIGN.md` are written in Korean.
 LLM markdown  →  normalize  →  render for channel  →  split safely  →  send
 ```
 
-1. **Normalize.** Agent output is not well-formed. Unpaired `**`, emphasis that spans a
-   line break in wrapped prose, unclosed code fences. Repair before rendering.
+1. **Normalize.** Agent-written Markdown may not render correctly through a standard
+   Markdown converter. Typical cases: 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. 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>`. Notion draws that bold as is
+   character goes out escaped (`\~`, `\<`), and emphasis that GFM would not close (`**(a)**`
+   followed directly by a Korean particle) goes out as `<strong>`. Notion renders that bold as is
    but shows inline HTML as text, so `notion-markdown` strips the tags and escapes a literal `*`
-   or `\` instead. For the browser, `html` draws
+   or `\` instead. For the browser, `html` renders
    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,
@@ -38,13 +39,11 @@ LLM markdown  →  normalize  →  render for channel  →  split safely  →  s
 3. **Split.** Respect the channel's limit — and never cut through markup. This also
    covers streaming: a chunk boundary must not land inside `**bold**`.
 
-Two options around that pipeline. **Input dialect:** an agent that learned Slack from its
-docs writes legacy `mrkdwn` (`*bold*`, `~strike~`, `<url|text>`); `--from slack-mrkdwn`
-reads it as such instead of as standard Markdown. **Change report:** how many times the
-normalizer stepped in — unclosed emphasis, unclosed fence, unpaired backticks, dropped
-markers — and what it rewrote for the channel — escaped characters, tags for emphasis,
-stripped HTML, bullets, tables, converted markers — so you can log how often the model
-breaks its own formatting and see what a channel changes before you adopt it.
+The pipeline has one option. **Repair report:** how many times the normalizer stepped
+in — unclosed emphasis, unclosed fence, unpaired backticks, dropped markers — and what it
+rewrote for the channel — escaped characters, tags for emphasis, stripped HTML, bullets,
+tables, converted markers — so you can log how often the model breaks its own formatting
+and see what a channel changes before you adopt it.
 
 ## Use it
 
@@ -53,10 +52,9 @@ cat agent-output.md | mdwire --channel telegram-html          # parts separated
 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 and rewrote (unclosed emphasis, escaped `~`, stripped tags, …) as one
-# JSON line on stderr.
-cat agent-output.md | mdwire --channel slack-markdown --from slack-mrkdwn --report
+# --report prints what the normalizer fixed and rewrote (unclosed emphasis, escaped `~`,
+# stripped tags, …) to stderr as one JSON line.
+cat agent-output.md | mdwire --channel slack-markdown --report
 ```
 
 ```rust
@@ -71,7 +69,7 @@ s.finish_into(&mut out);       // flush, closing anything left open
 import { render, renderWithReport, Streamer } from "@minjun0219/mdwire";   // npm — bundlers, Node, Bun
 
 const parts = render(markdown, "telegram-html");
-const { repairs } = renderWithReport(markdown, "slack-markdown", { from: "slack-mrkdwn" });
+const { repairs } = renderWithReport(markdown, "slack-markdown");
 
 // 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.
@@ -121,22 +119,31 @@ every file one character and 64 characters at a time and reports any divergence.
 `SPEC.md` §8.2.
 
 The streamer holds back only what it must: a prefix it cannot classify yet, a marker run
-at the end of a chunk, and the inside of an emphasis that has not closed. Paragraphs are
+at the end of a chunk, and the inside of an emphasis that has not closed. A whole paragraph is
 never held — a renderer that waits for a newline is not streaming.
 
 ## Why another one
 
-Three gaps in what exists today, each measured rather than assumed:
+We found three gaps in existing tools:
 
-- **Broken input is the normal case.** In a sample of 60 agent-generated documents,
+- **Emphasis spanning lines is common.** In a sample of 60 agent-generated documents,
   44 contained emphasis spanning a line break. A regex-based converter mispaired those
   into *inverted* emphasis ranges — and the channel returned HTTP 200, so nothing caught it.
-- **CJK is guessed at.** One converter pads emphasis with U+200B next to Korean text;
-  another does not. Neither measured the channel. We did: Slack `markdown_text` follows
-  CommonMark, so `_italic_` dies next to a Korean particle and `*italic*` lives. mdwire
-  emits `*` and pads nothing.
-- **Streaming has no answer.** Every converter is batch: parse the whole document, build an
-  AST, render. When tokens arrive incrementally, markup splits across chunk boundaries.
+- **Common Korean notation collides with Markdown.**
+  - In `**설정(config)**을` or `**52%**다`, the bold ends in a symbol and a particle follows right
+    after. Under CommonMark's rules the bold does not close and the `**` shows as text. GitHub and
+    browser renderers follow those rules.
+  - In `약 ~40km, 5~6월`, tildes mark an approximation and a range. With two of them in one
+    paragraph, GitHub (GFM), which reads a single `~` as strikethrough, pairs them and strikes
+    everything in between (`40km, 5`).
+
+  The two converters we compared disagree on Korean-adjacent emphasis (one pads it with U+200B, the
+  other leaves it alone), and neither checked the channel. mdwire measured each channel: on GitHub it writes just that
+  bold as `<strong>` and escapes a literal `~` as `\~`.
+- **Chat-channel converters ignore streaming.** Some browser renderers, like Streamdown, patch
+  unclosed syntax while tokens stream in. The Telegram and Slack converters we looked at all
+  take the whole document and convert it in one pass. When tokens arrive incrementally,
+  markup splits across chunk boundaries.
 
 ## Design
 
@@ -164,14 +171,16 @@ 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.9/mdwire-0.1.9.tgz
+npm install https://github.com/minjun0219/mdwire/releases/download/v0.1.11/mdwire-0.1.11.tgz
 
-# CLI binary — macOS (Apple silicon) or Linux (x86_64)
-curl -L https://github.com/minjun0219/mdwire/releases/download/v0.1.9/mdwire-v0.1.9-aarch64-apple-darwin.tar.gz | tar xz
-curl -L https://github.com/minjun0219/mdwire/releases/download/v0.1.9/mdwire-v0.1.9-x86_64-unknown-linux-gnu.tar.gz | tar xz
+# CLI binary — pick your platform
+curl -L https://github.com/minjun0219/mdwire/releases/download/v0.1.11/mdwire-v0.1.11-aarch64-apple-darwin.tar.gz | tar xz        # macOS, Apple silicon
+curl -L https://github.com/minjun0219/mdwire/releases/download/v0.1.11/mdwire-v0.1.11-x86_64-unknown-linux-gnu.tar.gz | tar xz    # Linux x86_64 (glibc)
+curl -L https://github.com/minjun0219/mdwire/releases/download/v0.1.11/mdwire-v0.1.11-aarch64-unknown-linux-gnu.tar.gz | tar xz   # Linux arm64 (glibc)
+curl -LO https://github.com/minjun0219/mdwire/releases/download/v0.1.11/mdwire-v0.1.11-x86_64-pc-windows-msvc.zip                 # Windows x86_64
 ```
 
-The release notes list a SHA-256 for every artifact — pin to it when installing by URL.
+The release notes list a SHA-256 for every artifact — verify the download against it when installing by URL.
 
 Or from source: `cargo install --path crates/mdwire-cli`.
 
@@ -189,10 +198,24 @@ s := mdwire.NewStreamer(mdwire.SlackMarkdown)
 s.PushTo(chunk, &out)   // no allocation per chunk
 s.FinishTo(&out)
 
-out := mdwire.RenderWith(input, mdwire.SlackMarkdown, mdwire.Options{From: mdwire.SlackMrkdwn})
+out := mdwire.RenderWith(input, mdwire.SlackMarkdown, mdwire.Options{})
 log.Printf("%+v", out.Repairs)
 ```
 
+## For coding agents
+
+mdwire ships an [agent skill](skills/mdwire/SKILL.md) that tells a coding agent when to reach for it,
+which channel and entry point to pick, and how to stream. It follows the Agent Skills format, so agents
+that read `SKILL.md` can use it directly. In Claude Code it installs as a plugin:
+
+```sh
+/plugin marketplace add minjun0219/mdwire
+/plugin install mdwire@mdwire
+```
+
+The site also serves [`llms.txt`](https://mdwire.minjun.dev/llms.txt), and its pages register a WebMCP
+tool, `mdwire_render`, so a browser agent on the site can run mdwire in the page.
+
 ## Building
 
 ```sh
@@ -200,7 +223,7 @@ log.Printf("%+v", out.Repairs)
 ./scripts/smoke.sh         # install it into a scratch project; call it from Node, Bun, and TypeScript
 ```
 
-The wasm binary is 111 KB, release with `wasm-opt`. The package carries two builds and
+The wasm binary is 111 KB (release build, after `wasm-opt`). The package carries two builds and
 picks by `exports` condition: `node` gets a CommonJS build that loads the wasm from disk,
 everything else gets the ESM bundler build. The script writes the root `package.json`
 itself: the crate has to stay `mdwire-wasm` because the core's library is already named

package/bundler/mdwire.d.ts

@@ -1,19 +1,17 @@
 /* tslint:disable */
 /* eslint-disable */
 
-/** 변환 옵션. 생략하면 표준 마크다운 입력이다. */
+/** Conversion options. Anything omitted uses the channel's default. */
 export interface RenderOptions {
-    /** 입력 표기. 슬랙 레거시 mrkdwn(`*굵게*` `~취소~`)으로 쓴 에이전트 출력이면 "slack-mrkdwn". */
-    from?: "markdown" | "slack-mrkdwn";
-    /** 조각 한도(글자 수). 생략하면 채널의 한도다 — 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[];
     };
 }
@@ -21,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>`).
+     * 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;