devel の成果を main に反映

.gitignore

@@ -0,0 +1,4 @@
+.DS_Store
+node_modules/
+workplace/*
+!workplace/.gitkeep

README.md

@@ -0,0 +1,125 @@
+# miku-docx2md
+
+`miku-docx2md` は、Word の `.docx` ファイルを Markdown に変換するローカル実行ツールです。
+
+見た目を Word どおりに再現するためのツールではありません。文章、見出し、リスト、表、リンクなどの文書構造を Markdown として読みやすく取り出すことを目的にしています。
+
+## できること
+
+- `.docx` ファイルを Markdown に変換
+- ブラウザだけでローカル変換
+- Node.js CLI で変換
+- 見出し、段落、箇条書き、番号付きリスト、表を出力
+- 太字、斜体、取り消し線、下線を一部保持
+- 外部リンクと解決可能な文書内リンクを出力
+- 解決可能な埋め込み画像を sidecar asset として出力
+- 変換サマリーを表示または保存
+- debug 用に unsupported 要素の HTML comment trace を出力
+
+## 使い方: ブラウザ
+
+`index.html` はランディングページです。変換本体は `miku-docx2md.html` で開きます。
+
+1. `index.html` を開きます。
+2. `miku-docx2md.html` へ進みます。
+3. `.docx` ファイルを選択します。
+4. 変換ボタンを押します。
+5. Markdown と summary を確認します。
+6. 必要に応じて Markdown、summary、画像 asset ZIP をダウンロードします。
+
+画像 asset ZIP は、変換結果に解決可能な埋め込み画像がある場合だけ利用できます。
+
+## 使い方: CLI
+
+```bash
+npm run cli -- ./sample.docx --out ./sample.md
+```
+
+summary も出力する例:
+
+```bash
+npm run cli -- ./sample.docx --out ./sample.md --summary --summary-out ./sample.summary.txt
+```
+
+画像 asset も出力する例:
+
+```bash
+npm run cli -- ./sample.docx --out ./sample.md --assets-dir ./sample.assets
+```
+
+debug comment も含める例:
+
+```bash
+npm run cli -- ./sample.docx --out ./sample.md --debug
+```
+
+## CLI オプション
+
+| Option | Description |
+| --- | --- |
+| `--out <file>` | Markdown の出力先 |
+| `--assets-dir <dir>` | 解決可能な埋め込み画像 asset の出力先 |
+| `--summary` | summary を標準出力へ表示 |
+| `--summary-out <file>` | summary の出力先 |
+| `--debug` | unsupported 要素の HTML comment trace を Markdown に含める |
+| `--include-unsupported-comments` | `--debug` と同じ |
+| `--help` | ヘルプを表示 |
+
+`--assets-dir` を指定すると、解決可能な画像は `word/media/example.png` のような package-relative path で保存されます。Markdown 側も、可能な場合は `[Image: ...]` placeholder ではなく相対 `![](...)` link を出力します。
+
+asset 出力先には `manifest.json` も作成されます。manifest には asset path、media type、alt text、byte size、source trace、block index、document position が含まれます。
+
+## 出力方針
+
+`miku-docx2md` は、Word の見た目ではなく文書構造を優先します。
+
+- Word のページレイアウトは再現しません。
+- 変換結果は GitHub-compatible Markdown / HTML に寄せます。
+- 表の結合セルは `←M←` と `↑M↑` の placeholder で簡略表現します。
+- 画像は本文内の完全再現ではなく、解決可能なものを asset として出力します。
+- unsupported 要素は通常 Markdown には出しません。
+- `--debug` 使用時のみ、unsupported 要素の trace を HTML comment として出します。
+
+## 主な対応内容
+
+| Content | Status |
+| --- | --- |
+| 段落 | 対応 |
+| 見出し | 対応 |
+| 太字、斜体、取り消し線、下線 | 一部対応 |
+| 段落内改行 | 対応 |
+| 外部リンク | 対応 |
+| 解決可能な文書内リンク | 対応 |
+| 箇条書き、番号付きリスト、ネスト | 対応 |
+| 表 | 対応 |
+| 表の結合セル | placeholder で簡略対応 |
+| 埋め込み画像 | 解決可能なものを sidecar asset として出力 |
+| Word の見た目の完全再現 | 非対応 |
+
+## ビルド
+
+```bash
+npm run build
+```
+
+`index-src.html`、`miku-docx2md-src.html`、`src/ts/` から、配布用の `index.html`、`miku-docx2md.html`、`src/js/` を再生成します。
+
+## テスト
+
+```bash
+npm run test:unit
+```
+
+## 詳細ドキュメント
+
+- 利用者向け補足: [docs/usage.md](./docs/usage.md)
+- 実文書での品質確認: [docs/quality-check.md](./docs/quality-check.md)
+- 仕様と設計方針: [docs/docx2md-spec.md](./docs/docx2md-spec.md)
+- 実装仕様: [docs/docx2md-impl-spec.md](./docs/docx2md-impl-spec.md)
+- upstream 参照方針: [docs/upstream.md](./docs/upstream.md)
+
+## License
+
+Apache License 2.0
+
+See [LICENSE](./LICENSE).

TODO.md

@@ -0,0 +1,121 @@
+# TODO
+
+## Phase 1: Project Skeleton
+
+- [x] Create `README.md`
+- [x] Create `docs/docx2md-spec.md`
+- [x] Create `docs/docx2md-impl-spec.md`
+- [x] Add project package metadata and test scripts
+- [x] Add `src/ts/` and `src/js/` skeleton
+- [x] Add minimal node runtime loader
+
+## Phase 2: Core Parsing Foundation
+
+- [x] Implement ZIP expansion in-house
+- [x] Implement XML utility helpers
+- [x] Implement relationship path resolution
+- [x] Implement minimal `.docx` document parser
+- [x] Implement minimal Markdown renderer
+
+## Phase 3: First-Cut Features
+
+- [x] Paragraph extraction
+- [x] Heading detection
+- [x] Inline formatting
+- [x] External hyperlinks
+- [x] Internal hyperlinks
+- [x] Lists with nesting
+- [x] Tables
+- [x] Merge placeholders `←M←` / `↑M↑`
+
+## Phase 4: Diagnostics
+
+- [x] Summary counts
+- [x] Unsupported element diagnostics
+- [x] Debug option for unsupported HTML comments
+
+## Phase 5: Tests
+
+- [x] Plain paragraph fixture
+- [x] Heading fixture
+- [x] Inline formatting fixture
+- [x] External hyperlink fixture
+- [x] Internal hyperlink fixture
+- [x] Nested list fixture
+- [x] Table fixture
+- [x] Unsupported element debug fixture
+
+## Phase 6: Post First-Cut Refinement
+
+- [x] Normalize internal bookmark anchors and internal hyperlink fragments
+- [x] Preserve list-like paragraphs inside table cells as simplified inline list text
+- [x] Classify unsupported elements in more detail than raw local-name passthrough where useful
+- [x] Preserve heading-like paragraphs inside table cells as simplified heading text
+- [x] Expand implementation docs for style inheritance depth and direct-format precedence
+
+## Phase 7: Next Expansion Candidates
+
+- [x] Emit debug unsupported-comment traces for unsupported elements nested inside supported blocks
+- [x] Allow limited plain-text extraction for `txbxContent` while keeping textbox layout unsupported
+- [x] Emit placeholder-like debug traces for unsupported image references with relationship targets when resolvable
+- [x] Add focused tests for nested unsupported traces in CLI output as needed
+
+## Phase 8: Richer Image Diagnostics
+
+- [x] Include image alt text in debug traces when drawing metadata exposes `descr` or `title`
+- [x] Include image dimensions from drawing metadata in debug traces when `wp:extent` is available
+- [x] Emit a minimal non-debug placeholder for images when meaningful alt text is available
+
+## Phase 9: Image Observability
+
+- [x] Count image references in conversion summary output
+- [x] Distinguish resolved embedded images from generic drawing-like unsupported objects in summary output
+
+## Phase 10: Image Asset Export
+
+- [x] Expose resolved embedded image package entries as parse-result assets in Node-oriented flows
+- [x] Count extracted image assets separately from image references in summary output
+- [x] Add CLI support for exporting resolved embedded image assets into a sidecar directory
+- [x] Emit relative `![](...)` image links in Markdown when sidecar asset export is enabled explicitly
+
+## Phase 11: Image Asset Metadata
+
+- [x] Prefer `[Content_Types].xml` declarations over extension inference when reporting exported image asset media types
+- [x] Expose downloadable image asset export in the browser UI as a ZIP archive
+
+## Phase 12: Asset Export Packaging
+
+- [x] Include `manifest.json` in CLI and browser asset exports
+- [x] Include source trace strings and owning block indexes in asset manifests
+- [x] Include finer manifest document positions with block kind and trace index
+
+## Phase 13: Real Document Quality Pass
+
+- [ ] Collect a small local validation set of real `.docx` documents
+- [ ] Run browser conversion against the validation set
+- [ ] Run CLI conversion against the validation set
+- [ ] Compare Markdown readability for headings, lists, links, tables, and image placeholders
+- [ ] Review generated summaries for obviously wrong counts
+- [ ] Review debug output for unsupported trace usefulness
+- [ ] Verify image asset export and `manifest.json` on documents with embedded images
+- [ ] Record recurring incompatibilities as focused fixtures or known limitations
+
+## Phase 14: Release Readiness
+
+- [ ] Re-read README from a first-time user perspective
+- [ ] Re-read `docs/usage.md` for CLI and browser workflow accuracy
+- [ ] Confirm generated `index.html` and `miku-docx2md.html` are in sync with source files
+- [ ] Run `npm run build`
+- [ ] Run `npm run test:unit`
+- [ ] Prepare release notes from user-visible changes
+
+## Phase 15: Refactoring
+
+- [ ] Review `miku-xlsx2md` module boundaries before cutting files
+- [ ] Split DOCX package loading and relationship/content-type resolution out of `core.ts` where useful
+- [ ] Split document XML block parsing, inline run parsing, table parsing, and drawing/image extraction out of `document-parser.ts`
+- [ ] Extract Markdown rendering/escaping helpers into focused modules instead of keeping rendering logic inside parser orchestration
+- [ ] Extract asset manifest construction and browser ZIP packaging into focused modules
+- [ ] Keep CLI and browser behavior unchanged while refactoring by adding or preserving focused regression tests
+- [ ] Update `scripts/lib/docx2md-module-order.mjs` and generated `src/js/` order whenever TypeScript modules are split
+- [ ] Re-run `npm run build` and `npm run test:unit` after each refactoring slice