Refactor architecture into eight components and consolidate reliability work
Build and publish container images / images (push) Successful in 9m34s
Release container images / release (push) Successful in 36s

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.
This commit is contained in:
Anya Tokugawa committed 2026-11-01 15:23:31 +09:00
1 parent 9dd425f765
commit d5d21b7841
302 files changed
+20037 -3492

No files matched your search

+117
View File
@@ -0,0 +1,117 @@
# エディタ改善サブプロジェクト
状態: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 の分離を合成データで検証する。