@cosense-toolbox/parser 0.1.0-beta.0 → 0.1.0-beta.2

package/README.md

@@ -1,794 +1,112 @@
 # @cosense-toolbox/parser
 
-Cosense (旧 Scrapbox) 記法のパーサー。
-位置情報つきの unist 風 AST を返す。
+Cosense (旧 Scrapbox) の記法を、位置情報つきの AST に変換する。
 
-> **beta**：公開 API はまだ変わりうる。
-> 安定するまでは `^` ではなくバージョンを固定して使うほうが安全。
+**ドキュメント → <https://cosense-toolbox.qaynam.dev/parser/>**
 
-```sh
-npm i @cosense-toolbox/parser@beta
-```
-
-```ts
-import { parse } from '@cosense-toolbox/parser'
-
-const page = parse('タイトル\nこれは [リンク] です')
-
-page.children[1].children
-// [ { type: 'text', value: 'これは ', position: {…} },
-//   { type: 'internalLink', label: 'リンク', target: 'リンク', position: {…} },
-//   { type: 'text', value: ' です', position: {…} } ]
-```
-
-- 依存は `effect` だけで、DOM も Node の API も使わない。
-- すべてのノードが位置情報を持つので、エディタのハイライトやキャレット連携に使える。
-- AST は plain object なので、`JSON.stringify` と `JSON.parse` で往復でき、worklet や postMessage を跨げる。
-- 記法と出力の両方をプラグインで拡張できる。
-- サブパスごとに export が分かれていて tree-shaking が効く (`parse` だけなら gzip 約 8 KB)。
-
-> このパッケージは Cosense (Scrapbox) の記法を解釈する非公式の実装である。
-> 開発元である Helpfeel社 とは関係がなく、公認も受けていない。
-
-## パース
-
-### parse
-
-ページ全文を受け取り、ブロックの並びを返す。
-どんな入力でも例外を投げず、必ず `Page` を返す。
-
-```ts
-import { parse } from '@cosense-toolbox/parser'
-
-const page = parse('タイトル\nこれは [リンク] です')
-
-for (const block of page.children) {
-  switch (block.type) {
-    case 'title':
-      console.log('title:', block.value)
-      break
-    case 'line':
-      console.log('line:', block.children.map((node) => node.type))
-      break
-    case 'codeBlock':
-      console.log(block.filename, block.lines.map((line) => line.value))
-      break
-    case 'table':
-      console.log(block.name, block.rows.length)
-      break
-    default:
-      // ノード型は minor で増えうるので default を置く
-      break
-  }
-}
-```
-
-`code:` と `table:` は、ページの文脈があって初めてブロックにまとまる。
-1 行目は無条件でタイトルとして扱う。
-
-### parseLine
-
-1 行だけを通常行としてパースする。
-エディタのように行単位で扱うときに使う。
-
-```ts
-import { parseLine } from '@cosense-toolbox/parser'
-
-parseLine('  > [リンク]')
-// LineBlock { indent: 2, quote: true, monospace: false, children: [...] }
-```
-
-ページの文脈がないので、`code:` と `table:` もブロックにはならず通常行になる。
-その行がページの何行目かは `{ line, offset }` で渡せる。位置情報がページ全体と揃う。
-
-### tokenizeInline
-
-行の中だけを解析して、インラインノードの並びを返す。
-
-```ts
-import { tokenizeInline } from '@cosense-toolbox/parser'
-
-tokenizeInline('[* 太字] と [リンク]') // → readonly InlineNode[]
-```
-
-改行を含まない 1 行分の文字列を渡す。
-
-### createParser
-
-拡張を固定したパーサーを作る。
-同じ拡張で何度もパースするときに、毎回 `extensions` を渡さずに済む。
-
-```ts
-import { createParser } from '@cosense-toolbox/parser'
-
-const parser = createParser({ extensions: [mentions] })
-parser.parse(source)
-parser.parseLine(line)
-```
-
-### asImageSrc
-
-画像 URL を `<img src>` に入れられる形にする。
-画像でなければ `null` を返す。
-
-```ts
-import { asImageSrc } from '@cosense-toolbox/parser'
-
-asImageSrc('https://gyazo.com/503a911fea542532aa5aba0a88eb7b60')
-// → 'https://i.gyazo.com/503a911fea542532aa5aba0a88eb7b60.png'
-asImageSrc('https://example.test/page')
-// → null
-```
-
-Gyazo のページ URL は画像そのものではないので、ここでだけ画像 URL に差し替わる。
-`parse` はこの変換をしない。AST はソースに書かれた文字列を保つ。
-
-### normalizeLineEndings
-
-CRLF と CR を LF に揃える。
-`parse` は必ずこれを通してから解析するので、位置情報を自分で計算するときに使う。
-
-## AST
-
-```
-Page
-├─ TitleBlock   1 行目。value に生テキスト、children にインラインノード
-├─ CodeBlock    code:filename とその配下 (CodeLine[])
-├─ TableBlock   table:name とその配下 (TableRow[] → TableCell[])
-└─ LineBlock    通常の行 (indent / quote / monospace + InlineNode[])
-```
-
-インラインノードは次の 10 種類で、すべて `type` で判別できる。
-
-| type | 記法 |
-| :--- | :--- |
-| `text` | 記法にならなかった素のテキスト |
-| `internalLink` | `[title]` |
-| `externalLink` | 裸の URL、`[url]`、`[url label]`、`[label url]` |
-| `projectLink` | `[/project/title]` (`project` と `title` に分解済み) |
-| `hashtag` | `#tag` |
-| `inlineCode` | `` `code` `` |
-| `image` | `[url.png]`、`[[url.png]]` (large)、`[linkUrl imageUrl]` (link つき) |
-| `icon` | `[user.icon]`、`[user.icon*5]` |
-| `formula` | `[$ x^2]` |
-| `decoration` | `[* 太字]` `[/ 斜体]` `[- 打消し]` `[_ 下線]` とその複合、`[[太字]]` |
-
-装飾は Markdown のような入れ子の強調にならない。
-Cosense では 1 つの記法が複数の装飾を同時に持つ (`[-/ x]` は打消しかつ斜体) ので、1 ノードが複数のフラグを持つ形にしている。
-
-`image` の `src` はソースに書かれた URL のままで、パーサーは書き換えない。
-Gyazo のページ URL (`https://gyazo.com/{hash}`) のように、そのままでは `<img>` に入れられない URL を表示用に直すのは描画側の仕事になる。
-その変換は [`asImageSrc`](#asimagesrc) が担当する。
-
-## 位置情報
-
-すべてのノードが `position` を持つ。
-
-```ts
-interface Point { line: number; column: number; offset: number }  // すべて 0-based
-interface Position { start: Point; end: Point }                   // end は exclusive
-```
-
-`line` はページ内の行番号で、0 がタイトル行になる。
-`column` は行内の文字オフセット、`offset` はページ全文の中の文字オフセットを指す。
-
-`source.slice(start.offset, end.offset)` は、その記法の生テキスト全体と一致する。
-`[` や `#` などのマーカーも含む。
-
-unist は 1-based だが、JS の `slice` とそのまま噛み合うよう 0-based を採用している。
-CRLF と CR は LF に正規化されてから解析されるので、位置は正規化後の文字列が基準になる。
-
-ノードの生テキストを切り出すには [`rawTextOf`](#rawtextof) を使う。
-
-## utils
-
-`@cosense-toolbox/parser/utils` は AST を走査して中身を取り出す。
-パースはしないので、AST を作る側と使う側を分けて import できる。
-
-### visit
-
-木を深さ優先で辿る。
-型を渡すとその型のノードだけが visitor に届く。
-
-```ts
-import { visit } from '@cosense-toolbox/parser/utils'
-
-visit(page, 'internalLink', (node) => {
-  console.log(node.target)
-})
-```
-
-visitor は `'skip'` を返すとそのノードの子を辿らず、`'exit'` を返すと走査全体を打ち切る。
-第 2 引数を省くとすべてのノードが届く。
-visitor の第 2 引数には、ルートからそのノードまでの祖先が配列で渡る。
-
-### find
-
-その型の最初のノードを返す。
-無ければ `null`。
-
-```ts
-import { find } from '@cosense-toolbox/parser/utils'
-
-find(page, 'codeBlock') // → CodeBlock | null
-```
-
-### collect
-
-その型のノードを出現順にすべて返す。
-
-```ts
-import { collect } from '@cosense-toolbox/parser/utils'
-
-collect(page, 'icon') // → IconNode[]
-```
-
-戻り値の型はノード型から導出されるので、`collect(page, 'icon')` は `IconNode[]` になる。
-
-### collectLinks
-
-内部リンクとハッシュタグの指す先を、出現順、重複なしで返す。
-
-```ts
-import { collectLinks } from '@cosense-toolbox/parser/utils'
-
-collectLinks(parse('t\n[A] と #B と [A]')) // → ['A', 'B']
-```
-
-### firstImage
-
-最初の画像ノードを返す。
-無ければ `null`。ページのサムネイルを選ぶときに使う。
-
-```ts
-import { firstImage } from '@cosense-toolbox/parser/utils'
-
-firstImage(page)?.src
-```
-
-### rawTextOf
-
-そのノードがソースで占めていた生テキストを返す。
-位置情報から切り出すので、記法のマーカーも含む。
-
-```ts
-import { rawTextOf } from '@cosense-toolbox/parser/utils'
-
-const source = 'title\nこれは [リンク] です'
-const link = parse(source).children[1].children[1]
-rawTextOf(source, link) // → '[リンク]'
-```
-
-## compile
-
-`@cosense-toolbox/parser/compile` は AST を別の形式に変える。
-この層はパーサー本体を import しないので、変換だけを使う側のバンドルにパーサーは入らない。
-
-### toHtml
-
-AST を HTML 文字列にする。
-引数はページ全体でなくてもよく、`parseLine` が返した 1 行でも AST の任意のノードでも受け取る。
-
-```ts
-import { parse } from '@cosense-toolbox/parser'
-import { toHtml } from '@cosense-toolbox/parser/compile'
-
-toHtml(parse('タイトル\nこれは [リンク] です'))
-```
-
-```html
-<div class="page">
-  <h1 class="title">タイトル</h1>
-  <div class="line">
-    これは <a class="link" href="/%E3%83%AA%E3%83%B3%E3%82%AF">リンク</a> です
-  </div>
-</div>
-```
-
-以降の HTML は読みやすさのために字下げして示す。
-実際の出力に要素間の空白は入らない。
-
-既定の見た目は [`@cosense-toolbox/style`](https://github.com/qaynam/cosense-toolbox/blob/main/packages/style/README.md) が別パッケージとして持っている。
-
-#### 出力の形
-
-class 名は接頭辞を持たず、すべて [`classNames`](#classnames) で差し替えられる。
-
-ブロックの対応は次のとおり。
-
-| 記法 | HTML |
-| :--- | :--- |
-| 1 行目 | `<h1 class="title">タイトル</h1>` |
-| 通常の行 | `<div class="line">本文</div>` |
-| 字下げした行 | `<div class="line" data-indent="2">本文</div>` |
-| 空行 | `<div class="line"><br></div>` |
-| `> 引用` | `<blockquote class="quote">引用</blockquote>` |
-| `$ ls` | `<code class="monospace">$ ls</code>` |
-
-ページ全体は `<div class="page">` で包まれる。
-インデントの深さは class ではなく `data-indent` 属性で表す。
-中点は要素を持たず、CSS の擬似要素が描く。
-本家と同じ `.indent-mark` と `.pad` と `.dot` の要素が要る場合は [`showPads`](#showpads) を渡す。
-
-テーブルは `<table>` になる。
-
-```html
-<table class="table">
-  <caption>テーブル名</caption>
-  <tbody>
-    <tr>
-      <td>abc</td>
-      <td>def</td>
-    </tr>
-  </tbody>
-</table>
-```
-
-コードブロックは本家と同じく 1 行を 1 要素に切る。
-
-```html
-<div class="line code-block">
-  <code class="code-start">
-    <span class="code-block-start">a.js</span>
-  </code>
-</div>
-<div class="line code-block" data-indent="1">
-  <code class="code-body">const a = 1</code>
-</div>
-```
-
-本体行はヘッダより 1 段深い `data-indent` を持つ。
-それより深い字下げは中身の文字列に残る。
-
-インラインの対応は次のとおり。
-
-| 記法 | HTML |
-| :--- | :--- |
-| `[title]` | `<a class="link" href="/title">title</a>` |
-| `https://a.test/x` | `<a class="link link-external" href="https://a.test/x">https://a.test/x</a>` |
-| `[https://a.test/x label]` | `<a class="link link-external" href="https://a.test/x">label</a>` |
-| `[/proj/page]` | `<a class="link link-project" href="/proj/page">/proj/page</a>` |
-| `#tag` | `<a class="hashtag" href="/tag">#tag</a>` |
-| `` `code` `` | `<code class="code">code</code>` |
-| `[a.png]` | `<img class="image" src="a.png" alt="">` |
-| `[[a.png]]` | `<img class="image" src="a.png" alt="" data-large="true">` |
-| `[user.icon]` | `<a class="link icon" href="/user">user</a>` |
-| `[$ x^2]` | `<span class="formula">x^2</span>` |
-
-装飾はフラグの集合を入れ子の要素に開く。
-
-```html
-<!-- [* 太字] -->
-<span class="decoration">
-  <strong>太字</strong>
-</span>
-
-<!-- [-/ x] は打消しかつ斜体 -->
-<span class="decoration">
-  <em>
-    <s>x</s>
-  </em>
-</span>
-
-<!-- [*** 見出し] -->
-<span class="decoration" data-size-level="2">
-  <strong>見出し</strong>
-</span>
-```
-
-見出しの段階は `data-size-level` 属性で表す。
-
-数式は組版せず、記法を外した中身をそのまま置く。
-KaTeX に渡したい場合は [`handlers`](#handlers) で差し替える。
-
-アイコンは既定では画像を出さない。
-[`iconImageUrl`](#iconimageurl) を渡すと `<img>` が入る。
-
-#### オプション
-
-| オプション | 型 | 既定 |
-| :--- | :--- | :--- |
-| [`pageUrl`](#pageurl) | `(title, node) => string` | `/{title}` |
-| [`iconImageUrl`](#iconimageurl) | `(node) => string \| null` | 常に `null` |
-| [`highlight`](#highlight) | `(code, language) => string` | 色付けしない |
-| [`classNames`](#classnames) | `HtmlClassNames` | `defaultClassNames` |
-| [`showPads`](#showpads) | `boolean` | `false` |
-| [`handlers`](#handlers) | `NodeHandlers<string>` | 既定のハンドラ |
-| [`style`](#style) | `string` | `<style>` を出さない |
-
-上の 3 つは、記法に書かれていないので AST から導けない情報を外から渡す。
-ページをどの URL で配信しているか、アイコン画像がどこにあるか、コードの構文がどう色分けされるかは、どれもソースには存在しない。
-残りは出力の見た目と構造を調整する。
-
-#### pageUrl
-
-```ts
-pageUrl?: (title: string, node: PageRefNode) => string
-```
-
-ページを指す記法の遷移先を決める。
-対象は `[title]` と `[/proj/page]` と `#tag` と `[user.icon]` の 4 つ。
-アイコンについてはリンク先だけを決め、画像は `iconImageUrl` が決める。
-
-`title` は記法に書かれたタイトルそのままで、`[title]` なら `title`、`[/proj/page]` なら `/proj/page`、`#tag` なら `tag`、`[user.icon]` なら `user` が渡る。
-ノード型で分岐する必要はない。
-
-```ts
-toHtml(page, { pageUrl: (title) => `/wiki/${encodeURIComponent(title)}` })
-```
-
-既定は `/{title}` で、区切りを含むタイトルは区切りを残して各段を encode する。
-`defaultPageUrl` として export しているので、独自のハンドラからも呼べる。
-
-外部リンクには効かない。
-外部リンクは記法そのものが URL なので、解決するものがない。
-
-#### iconImageUrl
-
-```ts
-iconImageUrl?: (node: IconNode) => string | null
-```
-
-`[user.icon]` の画像 URL を決める。
-`null` を返すと `<img>` を出さず、ユーザー名のテキストリンクになる。
-
-```ts
-toHtml(page, {
-  iconImageUrl: (node) => `/api/pages/help-jp/${encodeURIComponent(node.user)}/icon`,
-})
-```
-
-```html
-<a class="link icon" href="/rakusai">
-  <img class="icon" src="/api/pages/help-jp/rakusai/icon" alt="rakusai" title="rakusai">
-</a>
-```
-
-既定が `null` なのは、本家の画像 URL がプロジェクト名を含む (`/api/pages/{project}/{user}/icon`) 一方で、記法にプロジェクト名が書かれていないためである。
-
-`[/icons/name.icon]` のように別プロジェクトを指す場合、`node.user` には `/icons/name` が入る。
-
-> **注意**：
-> `https://scrapbox.io/api/pages/{project}/{user}/icon` は `Cross-Origin-Resource-Policy: same-origin` を返す。
-> scrapbox.io 以外のページの `<img>` からは読めず、`Access-Control-Allow-Origin` も無いので `crossorigin` 属性でも回避できない。
-> 別オリジンで表示するなら、自前のサーバーやワーカーで中継してそちらに向ける。
-
-#### highlight
-
-```ts
-highlight?: (code: string, language: string) => string
-```
-
-コードブロックの中身を色付けする。
-シグネチャは markdown-it の同名オプションと同じなので、たいていのハイライタがそのまま嵌る。
-
-```ts
-import hljs from 'highlight.js'
-
-toHtml(page, {
-  highlight: (code, language) =>
-    hljs.highlight(code, { language: hljs.getLanguage(language) ? language : 'plaintext' }).value,
-})
-```
-
-`language` はファイル名から推測した名前で、拡張子があればそれ、無ければファイル名全体が渡る。
-`code:hello.js` なら `js`、`code:python` なら `python` になる。
-言語名の綴りはライブラリごとに違うので、必要なら受け取った側で読み替える。
-
-戻り値は HTML としてそのまま埋め込まれるので、エスケープはハイライタの責任になる。
-
-これを渡すと、コードブロックの本体は 1 行 1 要素ではなく 1 つの要素にまとまる。
-ハイライタの出力が複数行にまたがるタグを含みうるためで、行で切るとタグが壊れる。
-ヘッダ行とファイル名は変わらない。
-
-```html
-<div class="line code-block">
-  <code class="code-start">
-    <span class="code-block-start">a.js</span>
-  </code>
-</div>
-<div class="line code-block" data-indent="1">
-  <code class="code-body highlight">…ハイライタの出力…</code>
-</div>
-```
-
-ライブラリごとの書きかたは次のとおり。
-
-```ts
-// Prism
-highlight: (code, lang) => Prism.highlight(code, Prism.languages[lang] ?? Prism.languages.plain, lang)
-
-// sugar-high
-highlight: (code) => sugarHigh(code)
-
-// Shiki は既定で <pre><code> ごと返すので、structure: 'inline' で中身だけにする
-const shiki = await createHighlighter({ themes: ['github-light'], langs: ['js'] })
-highlight: (code, lang) => shiki.codeToHtml(code, { lang, theme: 'github-light', structure: 'inline' })
-```
+- 依存は `effect` だけ。DOM も Node の API も使わないので、ブラウザでも Node でも Workers でも動く
+- どのノードも元のテキストの何行目の何文字目から始まるかを持つので、エディタの色付けやカーソル位置の判定に使える
+- AST はメソッドを持たないただのオブジェクト。`JSON.stringify` して保存しておき、あとで読み直せる
+- 記法そのものを増やせる。プロジェクト固有の書きかたも元からある記法と同じように扱える
+- パースだけなら gzip 約 8 KB。HTML 変換や走査は別の import 元なので、使わなければバンドルに入らない
 
-ハイライタのテーマ CSS が特定の class を要求する場合は `classNames` で足せる。
+> **beta**：公開 API はまだ変わりうる。安定するまではバージョンを固定して使うほうが安全。
 
-```ts
-toHtml(page, { highlight, classNames: { codeHighlight: 'highlight hljs' } })
-```
+### 次のリリースでの変更
 
-#### classNames
+- 記法の拡張 (`InlineConstruct` / `BracketRule`) は、成立しなければ **`null` を返す**普通の関数になった。
+  これまでは effect の `Option` を返す必要があり、拡張を書くのに effect が要った。
+  `Option.none()` は `null` に、`Option.some(x)` は `x` に書き換える。
+- 拡張のルールに渡る文脈から `bracketRules` を外した。拡張から使う場面が無く、中の型が漏れていたため。
 
-```ts
-classNames?: HtmlClassNames
-```
+### 0.1.0-beta.1 の変更
 
-出力する要素に付ける class 名を差し替える。
-指定したキーだけが既定を上書きする。
+beta.0 から上げるときは次の 2 点に注意。
 
-```ts
-toHtml(page, { classNames: { line: 'my-2 leading-7', internalLink: 'text-sky-600 underline' } })
-```
-
-値は置き換えであって追加ではない。
-既定の名前を残したまま足すなら `'line my-2'` のように自分で並べる。
-空文字を渡すと class 属性そのものを出さない。
+- サブパス `./plugin` を **`./extensions`** に改名した。渡すものが `Extension` で
+  オプション名も `extensions` なのに、置き場所だけ別の語彙だったため。
+  コンパイラを書くための型 (`NodeHandlers` 等) は `./compile` にある。
+- `decoration` ノードに **`markers`** を足した (必須)。書かれた装飾記号が
+  出現順・重複なしで入る。`toHtml` はこれを `deco-*` のような class として出す。
+  装飾ノードを自分で組み立てている拡張は追随が要る。
 
-既定の一覧は `defaultClassNames` として export している。
-キーはノード型のほか、要素を持つ細部にも用意してある。
+記号を増やす [`customDecorations`](https://cosense-toolbox.qaynam.dev/parser/extend/) も足した。
 
-| キー | 対象 |
-| :--- | :--- |
-| `page` `title` `line` | ページ全体、1 行目、通常の行 |
-| `quote` `monospace` | 引用行の `<blockquote>`、等幅行の `<code>` |
-| `codeBlock` | コードブロックに属する行 (ヘッダと本体の両方) |
-| `codeStart` `codeFilename` `codeBody` `codeHighlight` | ヘッダの `<code>`、ファイル名、本体の `<code>`、色付けした本体に足す class |
-| `indentMark` `pad` `dot` | `showPads` のときだけ出る要素 |
-| `internalLink` `externalLink` `projectLink` `hashtag` | 各リンク |
-| `inlineCode` `image` `icon` `formula` `decoration` `table` | 各インライン記法とテーブル |
+## インストール
 
-#### showPads
-
-```ts
-showPads?: boolean
-```
-
-インデントを本家と同じ要素として書き出す。
-深さ 1 段につき `pad` が 1 つ並び、その右端に中点が付く。
-
-```html
-<div class="line" data-indent="2">
-  <span class="indent-mark">
-    <span class="pad"> </span>
-    <span class="pad"> </span>
-    <span class="dot"></span>
-  </span>
-  字下げ
-</div>
-```
-
-既定では要素を出さず、深さは `data-indent` 属性だけで表す。
-中点は CSS の擬似要素で描けるので、見た目はどちらでも変わらない。
-
-#### handlers
-
-```ts
-handlers?: NodeHandlers<string>
-```
-
-ノード型ごとの出力そのものを差し替える。
-既定のハンドラに自動で重ねられるので、変えたい型だけ書けばよい。
-
-```ts
-toHtml(page, {
-  handlers: { formula: (node) => katex.renderToString(node.value) },
-})
-```
-
-ハンドラは `(node, ctx)` を受け取る。
-`ctx.children(node)` で子ノードの変換結果が配列で得られる。
-
-```ts
-handlers: {
-  line: (node, ctx) => `<p>${ctx.children(node).join('')}</p>`,
-}
-```
-
-既定のハンドラ一式は `createHtmlHandlers(options)` で取れる。
-既定の出力を包みたいときに使う。
-
-拡張が足した独自のノード型も、`InlineNodeMap` を declaration merging で拡張してあればここのキーになる。
-ハンドラを書かなかった独自ノードは、子があればその中身が出力される。
-
-#### style
-
-```ts
-style?: string
-```
-
-渡した CSS を `<style>` 要素として出力の先頭に差し込む。
-
-```ts
-import css from '@cosense-toolbox/style/style.css?raw'
-
-toHtml(page, { style: css })
-// <style>…</style><div class="page">…</div>
-```
-
-iframe の `srcdoc` のように、1 つの文字列で完結させたいときに使う。
-CSS そのものはこのパッケージに含まれていない。
-
-#### 独自のハンドラを書く
-
-`handlers` で要素ごと差し替えると、既定のハンドラがやっているエスケープと URL の検査が無くなる。
-同じことをするための部品を export している。
-
-| export | 役割 |
-| :--- | :--- |
-| `escapeHtml(value)` | `& < > " '` を実体参照にする |
-| `safeHref(url)` | href に入れて安全な URL だけを返す。script が動くスキームなら `null` |
-| `safeSrc(url)` | src 版。`data:` 画像は許す |
-| `defaultPageUrl(title)` | `pageUrl` の既定の実装 |
-| `defaultClassNames` | 既定の class 名 |
-
-外部リンクを別タブで開く例を示す。
-
-```ts
-import { escapeHtml, safeHref, toHtml } from '@cosense-toolbox/parser/compile'
-
-toHtml(page, {
-  handlers: {
-    externalLink: (node) => {
-      const href = safeHref(node.target)
-      return `<a class="link link-external" href="${escapeHtml(href ?? '')}" target="_blank" rel="noreferrer">${escapeHtml(node.label)}</a>`
-    },
-  },
-})
-```
-
-ハンドラは `classNames` の設定を受け取らない。
-両方を使う場合、class 名は書いた側で決めることになる。
-
-#### エスケープと URL の検査
-
-既定のハンドラは、テキストと属性値をすべてエスケープする。
-`javascript:` と `vbscript:` のスキームは href と src の両方から落とし、`data:` は href からだけ落とす。
-`data:` 画像には正当な使い道があるためである。
-
-スキームの判定では、先に空白と制御文字を落とす。
-ブラウザは途中にタブや改行が挟まった `javascript:` もスキームとして解釈するので、それを潰す。
-
-`handlers` と `highlight` が返した文字列はそのまま埋め込む。
-そこでのエスケープは書いた人の責任になる。
-
-### toPlainText
-
-記法を外したテキストを返す。
-オプションは無い。
-
-```ts
-import { toPlainText } from '@cosense-toolbox/parser/compile'
-
-toPlainText(parse('タイトル\n[* 太字] と [リンク]'))
-// 'タイトル\n太字 と リンク'
+```sh
+npm i @cosense-toolbox/parser@beta
 ```
 
-インデントは半角 2 文字、引用は `> ` として残る。
-コードブロックとテーブルは中身がそのまま出る。
+既定の見た目が要るなら [`@cosense-toolbox/style`](https://github.com/qaynam/cosense-toolbox/tree/main/packages/style) を別途入れる。
 
-### createCompiler
-
-HTML 以外を出すときに使う。
-`toHtml` も `toPlainText` もこれで書かれている。
+## 使ってみる
 
 ```ts
-import { createCompiler } from '@cosense-toolbox/parser/compile'
+import { parse } from "@cosense-toolbox/parser"
+import { collectLinks } from "@cosense-toolbox/parser/utils"
+import { toHtml } from "@cosense-toolbox/parser/html"
 
-const toMarkdown = createCompiler<string>({
-  handlers: {
-    internalLink: (node) => `[[${node.target}]]`,
-    decoration: (node, ctx) => `**${ctx.children(node).join('')}**`,
-    text: (node) => node.value,
-  },
-  fallback: (node, ctx) => ctx.children(node).join(''),
-})
-```
+const page = parse(`今日のメモ
+[プロジェクトA] の進捗を確認する
+#あとで読む`)
 
-`handlers` の型はノード型のマップから導出されるので、ノード型が増えても型が追随する。
-`fallback` はハンドラの無いノード型に使われる。
-
-## schema
-
-`@cosense-toolbox/parser/schema` は、worklet や postMessage を跨いで受け取った、本当に `Page` か分からない値を検証する。
-
-```ts
-import { decodePage } from '@cosense-toolbox/parser/schema'
-import { Either } from 'effect'
-
-const decoded = decodePage(JSON.parse(input))
-if (Either.isRight(decoded)) {
-  // decoded.right は Page
-}
+collectLinks(page) // → ['プロジェクトA', 'あとで読む']
+toHtml(page) // → '<div class="page"><h1 class="title">今日のメモ</h1>…'
 ```
 
-パース自体は失敗しないので、このサブパスが要るのは外から来た値を扱うときだけになる。
-
-## plugin
+## API
 
-`@cosense-toolbox/parser/plugin` は、記法を足す `InlineConstruct` と `BracketRule` と `Extension`、出力を足す `NodeHandlers` の型を公開する。
-このサブパスは型だけを持ち、実行時のコードを含まない。
+モジュールごとに export が分かれている。使うものだけ import すればよい。
 
-### 記法を拡張する
+| モジュール                           | 役割                                                | API                                                                                     |
+| :----------------------------------- | :-------------------------------------------------- | :-------------------------------------------------------------------------------------- |
+| `@cosense-toolbox/parser`            | テキストを AST にする                               | `parse` `parseLine` `tokenizeInline` `createParser` `asImageSrc` `normalizeLineEndings` |
+| `@cosense-toolbox/parser/utils`      | ヘルパー。AST から取り出す                          | `visit` `find` `collect` `collectLinks` `firstImage` `rawTextOf`                        |
+| `@cosense-toolbox/parser/html`       | AST を HTML 系の出力 (hast と HTML の文字列) にする | `toHast` `toHtml` `codeLineNumbers` `tableCellLineBreaks`                               |
+| `@cosense-toolbox/parser/compile`    | AST を HTML 以外の形式にする                        | `toPlainText` `createCompiler`                                                          |
+| `@cosense-toolbox/parser/extensions` | 記法を足す                                          | `Extension` `InlineConstruct` `BracketRule` `customDecorations` `tableCellNotation`     |
+| `@cosense-toolbox/parser/schema`     | 外から来た値を検証する                              | `decodePage`                                                                            |
 
-`Extension` を作って `parse` か `tokenizeInline` に渡す。
-既定のルールより先に試されるので、既存の記法を上書きすることもできる。
-
-```ts
-import { Option } from 'effect'
-import { parse } from '@cosense-toolbox/parser'
-import type { Extension, InlineConstruct } from '@cosense-toolbox/parser/plugin'
+各 API の詳細はドキュメントにある。
 
-const mention: InlineConstruct = (source, index) => {
-  if (source[index] !== '@') return Option.none()
-  const match = source.slice(index + 1).match(/^[A-Za-z0-9_-]+/)
-  if (!match) return Option.none()
-  return Option.some({
-    node: { type: 'internalLink', label: `@${match[0]}`, target: match[0] },
-    length: match[0].length + 1,
-  })
-}
+| ページ                                                                 | 内容                                                      |
+| :--------------------------------------------------------------------- | :-------------------------------------------------------- |
+| [概要](https://cosense-toolbox.qaynam.dev/parser/)                     | インストールと、どの API を使うかの早見表                 |
+| [例](https://cosense-toolbox.qaynam.dev/parser/demo/)                  | 記法をひととおり変換した結果とコード                      |
+| [パース](https://cosense-toolbox.qaynam.dev/parser/parse/)             | `parse` / `parseLine` / `tokenizeInline` / `createParser` |
+| [AST と位置情報](https://cosense-toolbox.qaynam.dev/parser/ast/)       | ノードの構造と `position` の意味                          |
+| [ヘルパー](https://cosense-toolbox.qaynam.dev/parser/utils/)           | `visit` / `find` / `collect` など                         |
+| [HTML への変換](https://cosense-toolbox.qaynam.dev/parser/html/)       | `toHast` / `toHtml` と 8 つのオプション                   |
+| [独自形式への変換](https://cosense-toolbox.qaynam.dev/parser/compile/) | `toPlainText` / `createCompiler`                          |
+| [記法の拡張](https://cosense-toolbox.qaynam.dev/parser/extend/)        | `Extension` と独自のノード型                              |
 
-const mentions: Extension = { constructs: [mention] }
-parse(source, { extensions: [mentions] })
-```
-
-`[...]` の中身の解釈を足すなら `bracketRules` を使う。
-同じ拡張で何度もパースするなら、`createParser({ extensions })` でパーサーを固定できる。
+## 互換性の方針
 
-### 独自のノード型を足す
+| 変更                                         | バージョン |
+| :------------------------------------------- | :--------- |
+| 新しいノード `type` の追加                   | minor      |
+| 既存ノードへの optional フィールド追加       | minor      |
+| オプションへの optional フィールド追加       | minor      |
+| 既存ノードのフィールドの削除、型変更、必須化 | major      |
+| `position` の意味論の変更                    | major      |
+| ノード `type` 文字列のリネーム               | major      |
 
-既存のノード型に寄せず新しい `type` を作る場合は、`InlineNodeMap` を declaration merging で拡張する。
-mdast と同じ手法で、`NodeHandlers` のキーにも `visit` の型引数にも自動で現れるので、描画まで型が通る。
+ノード型は minor で増えうるので、`switch (node.type)` には `default` を置いておく。
 
-```ts
-declare module '@cosense-toolbox/parser' {
-  interface InlineNodeMap {
-    mention: { type: 'mention'; user: string; position: Position }
-  }
-}
+## 開発
 
-// 記法を足す
-const mention: InlineConstruct = (source, index) => { /* → { type: 'mention', user } */ }
+規約は [CLAUDE.md](./CLAUDE.md) にある。
 
-// 描画を足す
-toHtml(page, {
-  handlers: { mention: (node) => `<a href="/u/${node.user}">@${escapeHtml(node.user)}</a>` },
-})
+```sh
+bun install
+bun run test
+bun run build
 ```
 
-ハンドラを書かなかった独自ノードは、子があればその中身が出力される。
-
-## 設計
-
-パースは総関数で、どんな入力でも例外を投げず必ず `Page` を返す。
-記法として成立しない部分は素のテキストになるだけで、エラーにはならない。
-
-I/O をしない。
-oEmbed の取得や動画判定のような URL の意味解決は、このパッケージの外の仕事になる。
-画像かどうかの判定だけは、記法の構造そのものを決めるので含んでいる。
-
-構造は micromark の「位置つきノードと記法ハンドラの登録制」と、markdown-it の「優先順位付きルールを先頭から試す」形を参考にしている。
-
-開発時の規約は [CLAUDE.md](./CLAUDE.md) にある。
-
-## 互換性の方針
-
-| 変更 | バージョン |
-| :--- | :--- |
-| 新しいノード `type` の追加 | minor |
-| 既存ノードへの optional フィールド追加 | minor |
-| オプションへの optional フィールド追加 | minor |
-| 既存ノードのフィールドの削除、型変更、必須化 | major |
-| `position` の意味論の変更 | major |
-| ノード `type` 文字列のリネーム | major |
-
-ノード型は minor で増えうるので、`switch (node.type)` には `default` を置いておくとよい。
-
 ## ライセンス
 
-MIT
+MIT。
+
+このパッケージは Cosense (Scrapbox) の記法を解釈する非公式の実装である。
+開発元である Helpfeel 社とは関係がなく、公認も受けていない。