Extract Grammaratur, Dregarnuhr, Geduldh, Mestionora, Ordoschnellic, Schutzaria, Kunstzeal and Seheweit behind compatible application contracts. Include accumulated editor resilience, navigation and theme UX, remote CLI, storage/schema and DR groundwork, tests and design/operations documentation. Verified: uncached full Go suite; go vet ./...; race tests for all eight components; 11 targeted Chromium tests; Node suites; 19 Python CLI tests; reproducible editor build. No push, release tag or deployment in this checkpoint.
118 lines
10 KiB
Markdown
118 lines
10 KiB
Markdown
# エディタ改善サブプロジェクト
|
||
|
||
状態:E1–E5 の初期実装と回帰検証完了。E6 は未実装・後続ゲート。
|
||
既存 HTML 正本・不変 Revision・Page UUID・言語別 head を維持する。
|
||
本書は `html-editor.md` の挿入パーツ設計を含むエディタ横断の実行計画。
|
||
|
||
2026-11-01:文書変換と情報保全の実装を `internal/grammaratur` へ分離。
|
||
通常変換・保護変換の契約と既存APIは維持する。
|
||
[コンポーネント命名と責務](component-names.md) に移行境界を定義する。
|
||
|
||
## 優先順位と完了条件
|
||
|
||
1. **E1 編集内容の保全**:端末内下書き、認証切れ/通信断/権限失効の区別、
|
||
再認証後の明示的な保存再開、保存完了を待つ `:wq`、二重保存防止。
|
||
2. **E2 保存競合**:言語別 head を DB トランザクション内で比較する CAS。
|
||
同一箇所を変更していないと確定できる範囲だけ自動マージし、その他は
|
||
基点/自分/最新の内容を表示して手動調整。相手の編集を無条件に上書きしない。
|
||
3. **E3 操作改善**:モバイルで Vim を使わない、macro 補完時の終端重複を防ぐ、
|
||
HTML/Markdown の切替で未保存データを捨てない、少数の挿入コンポーネント。
|
||
4. **E4 履歴・言語**:旧 Revision を作業バッファに読み込み、確認保存で新 Revision。
|
||
BCP 47 の明示言語は暗黙に `und` へフォールバックして上書きしない。
|
||
翻訳は同じ Page UUID の別言語として分岐し、URL Path を別 Page にしない。
|
||
5. **E5 変換保全**:HTML→Markdown→HTML の構造比較。不一致なら HTML を
|
||
`{=html}` 保護フェンス内に保持する。projection 展開結果を正本や下書きへ保存しない。
|
||
6. **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件ずつ追加取得し、現在言語で絞り込む。分岐は翻訳生成ではなく本文のコピー。
|
||
- 挿入は子ページ・表・画像キャプション・補足・コード・引用の6種の初期パレット。
|
||
画像 URL 等のプレースホルダーは編集が必要。ファイルピッカー、図形・外部 widget の
|
||
パラメータ編集、プラグインによる挿入パーツ登録は既存の HTML editor 設計に残る。
|
||
- touch/coarse pointer + hover 不可の端末ではデスクトップの Vim 設定を上書きせず、
|
||
当該編集セッションだけ通常入力にする。実機 iOS/Android の IME は別途受入試験。
|
||
|
||
## 次段階の実装順序
|
||
|
||
1. **E6a presence**:編集中リースの共有ストアと認可付き API、別端末を含む表示。
|
||
管理者にだけ見える監視ではなく、同じ Page/language を編集できる参加者に限定する。
|
||
2. **E6b realtime**:下記 CRDT 詳細設計・採用ライブラリ・同時変換ルールを確定した後に
|
||
feature flag 付きで実装。現時点の CAS を最終コミット時の保護として残す。
|
||
3. **E5b / E3b**:HTML ブロック単位の保護、hosted editor/CLI への保護フェンス対応、
|
||
アセットピッカーと拡張挿入パーツ。通常の Markdown だけを扱う外部エディタへ
|
||
このフェンスを無断で渡さない。既存の外部エディタ変換経路は本変更の対象外。
|
||
4. 保存 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 の分離を合成データで検証する。
|