宣言的UI移行台帳
- 開始日: 2026-11-12
- ブランチ:
feat/declarative-ui-migration - 起点コミット:
5c7d41fc(feat/mdx-pluginのマージ。810acafdを含む) - worktree:
C:/Users/rerur/.wk/program/riebeckite-declarative-ui - 担当: オーケストレーションエージェント
- 対象:
packages/plugins/(85プラグイン)。続いてpackages/ui、packages/runtime、packages/integrations/honox、packages/spa、packages/diagram、Themes、公式Scaffold。
この台帳を、監査状況・判断・検証・次の作業のSource of Truthとする。監査、実装、検証のたびに更新する。
ステータス
NOT_AUDITED、AUDITED、MIGRATION_REQUIRED、IN_PROGRESS、IMPLEMENTED、VERIFIED、KEEP_IMPERATIVE、NOT_APPLICABLE、BLOCKED、UNVERIFIED。
分類
- A — 完全な宣言的移行: JSXとコンポーネント状態がUIを自然に所有できる。
- B — ハイブリッド移行: UIはJSXへ移せるが、配置・ポインター・サイズ測定・フォーカス・fetch などのブラウザAPIは命令的に残る。
- C — 命令的実装を維持: JSX化が複雑性・コスト・性能を悪化させる、または操作が本質的に命令的である。
- D — 対象外: ビルド時のAST・データ・サーバー処理、またはクライアントDOMを所有しない既存の宣言的SSR。
監査方法
- 全プラグインの契約 (
renderers、pageTypes、markdownComponents、hastTransforms、clientEntries、extendMarkdownPipeline、extendHtmlPipeline) を棚卸しする。 - テストとdist以外のソースでDOM APIの使用を数える (
querySelector、createElement、replaceChildren、innerHTML、addEventListener、MutationObserver、classList、setAttribute、textContent、dataset、Canvas・SVG)。 - 実質的なクライアントモジュールを読み、描画と状態の所有先を判定する。
- ベースラインを測定し、移行後に再監査する。
分類一覧
A — 完全な宣言的移行
| プラグイン | 状態 | 担当 | 理由 |
|---|---|---|---|
flashcards |
VERIFIED | primary | デッキUIをクライアントで全体構築しており (createDeckUi、createElement 7箇所)、状態機械 (position、revealed、order) が小さい。FlashcardsDeck がHono JSXの useState で直接所有し、クライアントはpayload解析とフォールバックだけを担う。 |
B — ハイブリッド移行
| プラグイン | 状態 | 担当 | 宣言化する部分 | 命令的に残す部分 |
|---|---|---|---|---|
search |
VERIFIED | primary | 検索結果リストの描画を SearchResults へ移行 |
ダイアログ制御、キーボード操作、フォーカス、fetch、AbortSignal |
lightbox |
VERIFIED | primary | ダイアログのマークアップと画像・キャプション・状態表示を LightboxDialog へ移行 |
<dialog> 制御、フォーカストラップ、画像読み込みイベント |
text-fragment |
VERIFIED | primary | ポップオーバーのマークアップと操作・ステータス状態を TextFragmentPopover へ移行 |
選択範囲の取得、範囲の座標計算、コピーのタイマー、対象外要素の判定、イベント解除 |
code-enhance |
VERIFIED | 既存作業 | CodeCopy は useState を使う宣言的Markdownコンポーネント |
折り返し・折りたたみはAST生成ブロック上に残る |
code-tabs |
VERIFIED | primary | タブグループを CodeTabsGroup HAST変換で描画 |
選択とキーボード状態は @riebeckite/ui/tabs が担当 |
image-compare |
VERIFIED | primary | ImageCompare はmanifest確定後にfinalizeされるdeferred Markdownコンポーネント |
ポインターキャプチャ、range入力、CSSカスタムプロパティ |
calculator |
KEEP_IMPERATIVE | primary | — | 分離されたruntimeが計算を所有済み。UIは静的SSRで、JSX状態に利点がない |
toc |
KEEP_IMPERATIVE | primary | SSRの TableOfContents JSX |
スクロール追従と現在見出しの更新 |
color-mode |
KEEP_IMPERATIVE | primary | SSRのトグルコンポーネント | 属性・localStorage・matchMedia の同期 |
navigation |
KEEP_IMPERATIVE | primary | SSRの SiteNav・SidebarNavigation JSX |
レスポンシブドロワーとフォーカス |
docs |
KEEP_IMPERATIVE | primary | SSRの DocsSidebar JSX |
スクロールと現在セクションの強調 |
source-files |
KEEP_IMPERATIVE | primary | SSRページとrenderer | ファイルツリー操作 |
share |
KEEP_IMPERATIVE | primary | SSRの ShareControls JSX |
navigator.share・クリップボード・フォーカス |
analytics |
KEEP_IMPERATIVE | primary | — | ページビュー記録のみでUIがない |
diff |
VERIFIED | primary | 履歴、ビューア、パネル、行を DiffHistory・DiffViewer・DiffPanel・DiffLine で描画。サーバーHTMLも同じコンポーネントを使う |
取得、select・コミット選択、ローディング制御 |
garden-explorer |
KEEP_IMPERATIVE | primary | ページとクライアントが既にHono JSXをhydrate | hydrate済みページ上の検索・絞り込み |
local-graph |
KEEP_IMPERATIVE | primary | クライアントが既に hydrateRoot でHono JSXを使用 |
SVGレイアウトと測定 |
C — 命令的実装を維持
| プラグイン | 理由 |
|---|---|
hover-preview |
プレビュー本体はテキスト2要素。コストの中心はfetch、hover・focusのスケジューリング、ビューポート配置。全ページにJSX runtimeを足すのは純増。 |
autocardlink |
カードはremarkプラグインがSSRし、クライアントは画像フォールバックとコピー表示だけを扱う。 |
ux |
読書進捗と先頭へ戻るボタンはアニメーションフレームごとにCSS変数・クラスを更新する。直接更新が効率的で、要素自体も小さい。 |
canvas |
Canvasエディタが描画・選択・ポインター状態を所有する。 |
d2、graphviz、mermaid、wavedrom、vega-lite、markmap、chartjs |
外部レンダラーがSVG・Canvas・DOMの出力とライフサイクルを所有する。 |
map |
MapLibreが地図Canvas、操作、DOMを所有する。 |
marp |
Marpがスライド描画を所有し、クライアントは4つのコントロールを生成してスライドの表示を命令的に切り替える必要がある。JSX化は実行時コストを増やすだけで状態を単純化しない。 |
meta-bind |
入力とバインディングをその場で拡張する。DOM契約そのものが機能。 |
excalibrain |
SVGグラフのレイアウトと操作。 |
D — 対象外 (クライアントDOMを所有しない)
alias、archive、article-metadata、attachment、backlinks、bases、breadcrumbs、changelog、citations、code-annotations、daily-notes、dataview、deploy、diagnostics、discord-embed、excalidraw、folder-pages、frontmatter-transformer、gallery、glossary、hard-breaks、highlight、icons、image-optimizer、kanban、l10n、media、mermaid-pele、mdx、obsidian-markdown、og-image、pdf、permalink、plantuml、properties、qr-code、quality、query、recent-posts、related-posts、rename、responsive-image、rich-embed、seo、series、shortcodes、sidenotes、svg-optimizer、taxonomy、timeline、vault-heatmap、webmention。
移行キュー
| 順序 | プラグイン | 分類 | 作業 | 状態 | テスト |
|---|---|---|---|---|---|
| 1 | flashcards |
A | デッキ描画を useState 付きHono JSXコンポーネントへ移す。payload解析とフォールバックは維持 |
VERIFIED | pnpm --filter @riebeckite/plugin-flashcards test (2/2)、tests/interactive-runtime/official.test.ts のflashcards・SPAケースがPASS |
| 2 | search |
B | 結果をJSXコンポーネントで描画。ダイアログ・キーボード・fetchは維持 | VERIFIED | pnpm --filter @riebeckite/plugin-search test (31/31)、test:browser (18/18) |
| 3 | lightbox |
B | ダイアログのマークアップをJSXで描画。ダイアログ制御は維持 | VERIFIED | pnpm --filter @riebeckite/plugin-lightbox test (6/6)、tests/interactive-runtime/official.test.ts のlightboxケースがPASS |
| 4 | text-fragment |
B | ポップオーバーをJSXで描画。選択・配置ロジックは維持 | VERIFIED | pnpm --filter @riebeckite/plugin-text-fragment test (21/21)、tests/interactive-runtime/official.test.ts のtext-fragmentケースがPASS |
| 5 | diff |
B | 履歴、ビューア、パネル、行をHono JSXで描画。取得とリビジョン選択は維持 | VERIFIED | pnpm --filter @riebeckite/plugin-diff test (18/18)、test:browser (1/1) |
| 6 | 再監査 | — | 全プラグインと依存パッケージを再走査 | VERIFIED | 85プラグインを分類(A 1、B 16、C 16、D 52)。未処理のA/B候補なし |
ベースライン
| 項目 | 移行前 | 移行後 |
|---|---|---|
flashcards パッケージのクライアント (dist/client.js、非minify) |
6,126 B | 6,440 B (+314 B) |
| Webサイトのflashcardsクライアントチャンク | 全ページで読み込み (client-Dbl1HkEF.js、125,439 B) |
遅延チャンク (client-DySzhhlf.js、2,959 B) と、Markdownコンポーネントが既に使う共有JSXクライアントruntime |
flashcards ソース内のDOM構築 |
デッキを組み立てる createElement 7箇所 |
0。JSXがマークアップと状態を所有 |
search パッケージのクライアント (dist/client.js、非minify) |
13,284 B | 13,577 B (+293 B) |
| Webサイトのsearchクライアントチャンク | 共有チャンク (client-Dbl1HkEF.js、125,439 B) に含まれ全ページで読み込み |
検索ページ用チャンク (client-D9tNpf5I.js、6,565 B)。presence selectorで制限 |
search クライアントのDOM構築 |
createElement などの呼び出し27箇所 |
0。SearchResults が項目を描画 |
| 対話的Markdownコンポーネントのhydration | runtime entryがあるサイトで失敗 (runtimeIds 引数の欠落) |
修正済み。生成クライアントの回帰テストと外部Scaffold E2Eで保証 |
lightbox パッケージのクライアント (dist/client.js、非minify) |
5,326 B | 5,600 B (+274 B) |
lightbox のダイアログ構築 |
dialog.ts の createElement 7箇所 |
ホスト要素の createElement 1箇所。残りは LightboxDialog がHono JSXで描画 |
| Webサイトのlightboxクライアントチャンク | 共有チャンク (client-Dbl1HkEF.js、125,439 B) に含まれ全ページで読み込み |
[data-lightbox-src] のpresence selectorで制限。client-sw_U6mX4.js (2,921 B) |
text-fragment パッケージのクライアント (dist/client.js、非minify) |
8,391 B | 9,292 B (+901 B) |
text-fragment のポップオーバー構築 |
text-fragment.client.ts の createElement 呼び出し4箇所 |
ホスト要素の createElement 1箇所。残りは TextFragmentPopover がHono JSXで描画 |
| text-fragmentクライアントの読み込み | 共有チャンク (client-Dbl1HkEF.js、125,439 B) |
全記事で選択共有が必要なため全ページ対象。共有 client-Bh6h2XFk.js (91,733 B) に含まれる |
diff パッケージのクライアント (dist/client.js、非minify) |
7,116 B | 8,010 B (+894 B) |
diff の描画 |
リビジョン変更ごとに innerHTML と escapeHtml で文字列を生成 |
DiffHistory・DiffViewer・DiffPanel・DiffLine がJSXで描画。公開関数は境界で renderToString を使い、サーバーHTMLも同じコンポーネントから生成 |
diff クライアントの後始末 |
後始末なし。再マウント後もリスナーが残る | AbortController と panelView.unmount() を initDiffHistory から返す |
| diffクライアントの読み込み | 全ページの共有チャンク | [data-rr-diff-history] のpresence selector |
flashcards のマークアップは FlashcardsDeck でサーバー描画できるが、既存の flashcards フェンスはpayloadを描画してクライアントでhydrateするため、コンテンツ移行は不要。
発見とリスク
- 既存の宣言的UI監査はなく、
defineMarkdownComponentを使うのはcode-enhanceだけ。 - Markdownコンポーネントは
riebeckite-componentフェンスとYAML propsから登録される。既存のMarkdown構文 (flashcardsフェンスなど) をコンテンツを壊さずにこのレジストリへ移せないため、互換性のある経路はクライアント側のJSX描画である。 presenceSelectorのないclientEntriesは全ページでモジュールをimportする。新しい任意ウィジェットはセレクタで読み込みを制限する。- Hono JSXはbooleanの
trueを空属性として描画し、falseを省略する。aria-pressedなどのARIA状態属性は明示的な文字列にする。 - 生成クライアントはMarkdownコンポーネントの
mountPluginClientInitializerにruntimeIds引数を渡していなかった。runtime entryを持つサイトでは、すべての対話的コンポーネントのhydrationが失敗していた。packages/integrations/honox/src/client_module.tsで修正し、回帰テストを追加した。 the excalidraw figure renders to SVG in the browserは/assets/HWを期待していたが、docs/assets/HW.mdは意図的にprivate: trueのため単独ページは生成されない。ブラウザテストは公開ドキュメント内の埋め込みを検証するよう修正し、単独ページの描画はpackages/plugins/excalidraw/test/excalidraw_page.test.tsで保証する。loadStandaloneSsgBundleはビルド済みエントリを?v=<timestamp>付きでimportしていたが、動的読み込みされるcontent-renderersチャンクは同じエントリをクエリなしでimportしていた。Nodeは別モジュールとして扱うためHono JSX runtimeが二重に読み込まれ、完全再生成時にMDXのノードがinstanceof判定に失敗した。安定したfile URLを使うよう修正し、URL契約の回帰テストを追加した。searchの選択状態はpropsでaria-selectedを再描画し、選択項目の可視化は描画後のscrollIntoViewに残した。フォーカスとキーボード処理は従来どおり命令的。- 検索結果のアイコンは従来もサニタイズ済みHTMLを
innerHTMLで挿入していた。SearchResultsは同じ信頼境界をdangerouslySetInnerHTMLで維持する。 - lightboxのダイアログは
createRootでホスト要素へ描画し、そのホストをdocument.bodyへ追加する。ネイティブ<dialog>の制御、フォーカストラップ、画像のload/errorイベントは命令的に残す。ブラウザテストのクリックは、トリガーのリンク遷移を防ぐためcancelableにする必要がある。 - text-fragmentのポップオーバーも
createRootでホスト要素へ描画し、document.bodyへ追加する。render()は非同期のため、表示状態の反映後にrequestAnimationFrameで配置する。選択範囲の取得、コピーのタイマー、イベント解除は命令的に残す。 - 最初の監査では、
diffの描画ファイルが.tsxであることから「既にHono JSX」と判断していた。しかしrenderDiffPanel・renderDiffLineはテンプレート文字列を返し、クライアントはinnerHTMLでパネルを書き換えていた。再監査でこれを訂正し、DiffPanel・DiffLineを実際のJSXコンポーネントにしてクライアントはcreateRootを使う。その後、履歴とビューアの外側マークアップもDiffHistory・DiffViewerへ移し、文字列を返す公開関数は互換性のための境界だけにした。 diffにはSPA向けの後始末がなかった。マウント時にリスナーを中断しパネルrootをunmountする後始末を返すようにし、パッケージのブラウザテストで描画と後始末の両方を確認する。- docsは英語・日本語の対と
docs/README.mdからの到達性を要求する。この台帳には日本語版とREADMEリンクを用意する。
完了監査
- 移行スコープは完了している。全プラグインを分類し、Aはすべて検証済み、Bの移行価値がある部分も検証済みで、残るC・Dの判断根拠は上記に記録した。
- 未分類の
createClientEntry利用者はなく、再監査で新たなA/B候補は見つからなかった。 - 外部ScaffoldのE2EはPASSする。
pnpm test:e2e:externalは公開tarballから外部サイトを構築し、[external-site] PASS: external site built from published artifactsで完了する。以前のTypeError: Cannot convert object to primitive valueはpackages/integrations/honox/src/ssg/standalone.tsの製品コードの不具合だった。キャッシュ破棄用クエリがSSGエントリのモジュールインスタンスを二重にし、Hono JSX runtimeも二重にしていた。RIEBECKITE_SSG_FULL_REGENERATION=1でMDX content rendererが動的importされる経路により、main16baeffeでも再現した。安定したモジュールURLへの修正で外部E2Eは通り、Scaffold上の対話的Markdownコンポーネントhydrationも確認できた。 the excalidraw figure renders to SVG in the browserは、テスト側の不正な/assets/HW期待を修正したことでPASSする。非公開コンテンツが単独ルートから除外されるのは正しい挙動で、ドキュメント埋め込みとプラグイン自身の単独ページテストが描画を保証する。- main
4977e308と後続のcontent mutation変更を統合した後の最終再監査でも、85プラグイン、32クライアントエントリ、1 A / 17 B / 15 C / 52 D。Phase 1〜4の実装でimage-compareはVERIFIED、code-tabsはBへ移動した。新たなA/B候補は残っていない。完了内容は実装監査に記録した。
次の作業
移行候補は残っておらず、外部Scaffold E2Eと公式ブラウザ操作テストを含む全検証ゲートがPASSしている。Phase 1〜4も完了し、deferred component props、HAST利用者、app slots、外部レンダラーの共通ライフサイクルが実装済み。ブランチはレビュー可能な状態であり、merge・push・deployは行っていない。
Powered by Riebeckite