11 KiB
エディタ改善サブプロジェクト
状態:E1–E5 の初期実装と回帰検証完了。E6 は未実装・後続ゲート。
既存 HTML 正本・不変 Revision・Page UUID・言語別 head を維持する。
本書は html-editor.md の挿入パーツ設計を含むエディタ横断の実行計画。
2026-11-01:文書変換と情報保全の実装を internal/grammaratur へ分離。
通常変換・保護変換の契約と既存APIは維持する。
コンポーネント命名と責務 に移行境界を定義する。
優先順位と完了条件
- E1 編集内容の保全:端末内下書き、認証切れ/通信断/権限失効の区別、
再認証後の明示的な保存再開、保存完了を待つ
:wq、二重保存防止。 - E2 保存競合:言語別 head を DB トランザクション内で比較する CAS。 同一箇所を変更していないと確定できる範囲だけ自動マージし、その他は 基点/自分/最新の内容を表示して手動調整。相手の編集を無条件に上書きしない。
- E3 操作改善:モバイルで Vim を使わない、macro 補完時の終端重複を防ぐ、 HTML/Markdown の切替で未保存データを捨てない、少数の挿入コンポーネント。
- E4 履歴・言語:旧 Revision を作業バッファに読み込み、確認保存で新 Revision。
BCP 47 の明示言語は暗黙に
undへフォールバックして上書きしない。 翻訳は同じ Page UUID の別言語として分岐し、URL Path を別 Page にしない。 - E5 変換保全:HTML→Markdown→HTML の構造比較。不一致なら HTML を
{=html}保護フェンス内に保持する。projection 展開結果を正本や下書きへ保存しない。 - E6 共同編集(後続):サーバーをまたぐ presence、選択範囲、CRDT/OT、 編集セッションと永続化境界。単なる同時保存やポーリングを共同編集と呼ばない。
保存と下書きの契約
- 正本の保存単位は Page UUID × canonical language。開始 head(空も有効)を
base_revision_uuidで渡す。比較と Revision 追加は同一 write transaction。 - 旧クライアントの base 未指定は移行互換として残す。UI は必ず base を指定する。 全入口の必須化・hosted editor/CLI 追従は後続ゲート。
- 401 は再ログイン、403 は権限の再確認。変換 API の失敗時には Markdown を HTML として保存しない。リダイレクト/非 JSON のログイン応答も成功にしない。
- 保存要求中の編集は別の dirty 状態として保持する。保存成功したスナップショット と現在内容が一致するときだけ下書きを削除する。応答喪失時は head 比較で回復する。
- 下書きは origin・Domain・Principal・Page・language 単位。別ユーザーの下書きを 自動表示しない。サーバー同期はしない。端末を共有する場合の平文保存リスクを明記。
- 端末ストレージは容量制限・拒否・プライベートモード・ブラウザー終了で失われ得る。 保存失敗を明示し、テキストのダウンロード導線を用意する。下書きには保存時刻、 形式、基点 Revision と基点内容を保持し、期限とサイズの上限を設ける。
- 復旧候補がある場合は無条件に server autosave しない。復元/破棄をユーザーが選ぶ。 再接続だけで公開 Revision を自動更新しない。
初期実装の API・UI と制限
POST /_/api/v1/revisions/save:任意のbase_revision_uuidを追加。 このエディタは常に指定し、409 を競合として処理する。editor_principal_uuidも照合し、 編集中に別アカウントへ切り替わった状態で保存しない。旧クライアントの無条件保存は残る。GET /_/api/v1/editor/state?uuid=…&lang=…:対象 Domain・Page の読取権限を検証。metadata=1は本文ファイルを読み込まず head を取得。revision=…は対象 Page の 過去本文を取得する。非表示タブでのポーリングは停止し、表示時は30秒間隔。 これは保存済みの別更新検出であり、未保存の同時編集者 presence ではない。POST /_/api/v1/editor/convert:作業中 HTML を安全な authoring Markdown に変換。POST /_/api/v1/render/markdownのauthoring:trueで保護フェンスを元の HTML に戻す。projection:trueと併用したプレビューでは従来の sanitizer・macro 展開を適用する。- 変換できない HTML は文書全体を保護する保守的な実装。フェンスは
```{=html}形式(本文にバッククォートがある場合はそれより長い区切り)。 任意の属性、コメント、未知要素、表の結合、画像キャプション、コード内空白を保持。 フェンス内を編集でき、外側に Markdown を追記できる。通常のコードフェンス内にある{=html}サンプルは HTML として実行しない。保全は実行許可を与えるものではない。 - 自動マージは各版を1つの変更範囲として比較する保守的方式。重複・隣接・同一挿入点は 手動確認へ回す。自動再保存は3回まで再照合し、それ以上は確認画面へ移行。 ファイル形式が変わった場合は自動マージせず退避と再読込を案内する。
- 下書きは
localStorage。UTF-8 JSON 全体で2 MiBまで、復元対象は7日以内。 起動時に期限切れを削除するため、ブラウザーを開かない期間の物理削除は保証しない。 Domain/Principal/Page/language/tab ごとに分離し、他タブの下書きを一括削除しない。 IndexedDB・サーバー同期・暗号化は未実装。保存失敗時はダウンロードを案内する。 +は挿入・下書き、文は言語の編集・分岐、↶は旧リビジョンを作業バッファへ 読み込む。復元は明示保存で新 Revision を追加し、旧 Revision を書き換えない。 履歴は50件ずつ追加取得し、現在言語で絞り込む。分岐は翻訳生成ではなく本文のコピー。- 挿入は子ページ・表・画像キャプション・補足・コード・引用・CSV macroの初期パレット。 画像 URL 等のプレースホルダーは編集が必要。ファイルピッカー、図形・外部 widget の パラメータ編集、プラグインによる挿入パーツ登録は既存の HTML editor 設計に残る。
- touch/coarse pointer + hover 不可の端末ではデスクトップの Vim 設定を上書きせず、 当該編集セッションだけ通常入力にする。実機 iOS/Android の IME は別途受入試験。
次段階の実装順序
CSVの表編集は既存保存・下書き・履歴の契約へ接続済みです。CSVはHTML変換と文字列自動マージを行わず、競合時は比較して採否を決めます。BOMと混在改行を保持するため、CSV初期値はHTMLのtextarea解析を通さず安全なJS文字列として渡し、CodeMirrorはLFのみで分割します。初期フォーカスの遅延処理も、表セルなどへ移ったフォーカスを奪いません。詳細な上限と残件は表設計を参照してください。
- E6a presence:編集中リースの共有ストアと認可付き API、別端末を含む表示。 管理者にだけ見える監視ではなく、同じ Page/language を編集できる参加者に限定する。
- E6b realtime:下記 CRDT 詳細設計・採用ライブラリ・同時変換ルールを確定した後に feature flag 付きで実装。現時点の CAS を最終コミット時の保護として残す。
- E5b / E3b:HTML ブロック単位の保護、hosted editor/CLI への保護フェンス対応、 アセットピッカーと拡張挿入パーツ。通常の Markdown だけを扱う外部エディタへ このフェンスを無断で渡さない。既存の外部エディタ変換経路は本変更の対象外。
- 保存 API の旧クライアント移行と base 必須化、下書き大容量化・明示破棄 UX、 共有端末ポリシー、モバイル実機テスト。
共同編集の詳細設計 TODO
- presence キーは Domain × Page UUID × language × Principal × tab session。 TTL 付きリース、退出、バックグラウンド抑制、権限失効時の購読停止を定義。
- API は
/_/api/v1/editor/配下に置く。WebSocket/SSE は origin・認証・対象 Page の read/write を接続時と継続時に検証。本文や利用者名を未認可者へ漏らさない。 - 本文 CRDT は authoring source(HTML/Markdown の混在規則と基点を含む)を同期し、 projection HTML を同期しない。言語・形式の不一致を同一 room に混在させない。
- SQLite に毎キー入力を記録しない。スナップショット間隔・増分上限・圧縮・GC・ HA 配信基盤と Revision commit 境界を定義。offline 分岐復帰・undo と IME を検証。
- Yjs/Automerge 等は権限、再接続、肥大化、ライセンス、bundle サイズを比較する。 この選択とサーバー共有状態を未設計のまま本番へ有効化しない。
検証・展開ゲート
テスト用 DB と合成文書だけを用いる。実データ・外部カレンダーにはアクセスしない。 保存 CAS、空 head、言語分離、旧 Revision 復元、認証失効、別 Principal、通信断、 変換失敗、保存中の追記、再試行、複数タブ、モバイル、IME、macro 終端、未知 HTML の round-trip を検証する。CRDT と複数インスタンス presence は別途負荷・安全性試験。 本番反映・リリース採番は実装検証の後に行い、既存リリースタグは変更しない。
初期回帰試験:TestEditorRevisionCAS、TestEditorResilienceAPI、
TestAuthoringRoundTrip / TestAuthoringProtectedHTML、assets/editor/editor-core.test.mjs。
実ブラウザーは PAGESWIKI_BROWSER_TEST=1 で TestEditorResilienceChromium と
TestHTMLProjectionChromium。通信断、401、応答喪失、競合 UI、自動マージ、保存中の追記、
変換失敗、下書き復元、旧版復元、言語分岐、マクロ補完、モバイル判定、テーマ、
authoring/projection の分離を合成データで検証する。