From 72d85ba032ffda0c071c79a48cedbea8abe3388f Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 22 May 2026 08:28:26 +0000
Subject: [PATCH] feat(editor): add Markdown source mode toggle as IME-safe
 fallback
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The Milkdown contenteditable mishandles IME composition on Windows —
committing a Zhuyin selection with Enter can revert to the raw phonetic
buffer and drop the last keystrokes. Add a per-editor toggle to a plain
<textarea> source mode, which the browser handles natively without any
composition side-effects (the comment box already proves this works).

The preference is persisted to localStorage so affected users set it once,
and both modes share a single markdown source-of-truth so toggling keeps
edits. All three call sites (PageEdit, NewPage, Admin) work unchanged via
the existing onChange/getMarkdown contract.

https://claude.ai/code/session_018z3pxtCp1KHRGv7UNNa5dS
---
 frontend/src/components/Editor/Editor.jsx | 111 ++++++++++++++++++++--
 frontend/src/index.css                    |  40 ++++++++
 frontend/src/locales/en.json              |   5 +
 frontend/src/locales/ja.json              |   5 +
 frontend/src/locales/ko.json              |   5 +
 frontend/src/locales/zh-TW.json           |   5 +
 6 files changed, 163 insertions(+), 8 deletions(-)

diff --git a/frontend/src/components/Editor/Editor.jsx b/frontend/src/components/Editor/Editor.jsx
index e210d40..8e143c3 100644
--- a/frontend/src/components/Editor/Editor.jsx
+++ b/frontend/src/components/Editor/Editor.jsx
@@ -1,4 +1,4 @@
-import { useEffect, useRef, forwardRef, useImperativeHandle } from 'react'
+import { useEffect, useRef, useState, forwardRef, useImperativeHandle } from 'react'
 import { useTranslation } from 'react-i18next'
 import { Editor as MilkdownEditor, rootCtx, defaultValueCtx, commandsCtx, serializerCtx, editorViewCtx } from '@milkdown/kit/core'
 import { commonmark, headingSchema, blockquoteSchema, hrSchema, bulletListSchema, orderedListSchema, codeBlockSchema, insertImageCommand } from '@milkdown/kit/preset/commonmark'
@@ -588,6 +588,20 @@ const Editor = forwardRef(function Editor({ defaultValue = '', onChange, onDrawi
   const mediaHandlerRef = useRef(onMediaPickerOpen)
   const onTabOutRef = useRef(onTabOut)
   const editorViewRef = useRef(null)
+  // Source ("plain Markdown") mode is a textarea-based fallback. The Milkdown
+  // contenteditable mishandles IME composition on Windows (committing a Zhuyin
+  // selection with Enter can revert to the raw phonetic buffer and drop the
+  // last keystrokes); a native <textarea> has none of that. The preference is
+  // persisted so affected users set it once.
+  const SOURCE_MODE_KEY = 'editor.sourceMode'
+  const [sourceMode, setSourceMode] = useState(
+    () => typeof localStorage !== 'undefined' && localStorage.getItem(SOURCE_MODE_KEY) === '1'
+  )
+  const sourceRef = useRef(null)
+  // Latest markdown, kept current in both modes so we can seed the other mode
+  // when the user toggles.
+  const markdownRef = useRef(defaultValue)
+  const [sourceText, setSourceText] = useState(defaultValue)
   // The slash menu and wikilink menu both render plain DOM (not React),
   // so they cannot read t() from context. Snapshot translated strings into
   // refs before the editor's init effect runs.
@@ -631,29 +645,54 @@ const Editor = forwardRef(function Editor({ defaultValue = '', onChange, onDrawi
   useImperativeHandle(ref, () => ({
     insertText(text) {
       const view = editorViewRef.current
-      if (!view) return
+      if (!view) {
+        // Source mode: splice at the textarea caret.
+        const ta = sourceRef.current
+        if (!ta) return
+        const start = ta.selectionStart ?? ta.value.length
+        const end = ta.selectionEnd ?? start
+        const next = ta.value.slice(0, start) + text + ta.value.slice(end)
+        markdownRef.current = next
+        setSourceText(next)
+        onChangeRef.current?.(next)
+        requestAnimationFrame(() => {
+          const el = sourceRef.current
+          if (!el) return
+          const caret = start + text.length
+          el.focus()
+          el.setSelectionRange(caret, caret)
+        })
+        return
+      }
       const { state, dispatch } = view
       const pos = state.selection.from
       dispatch(state.tr.insertText(text, pos))
     },
     focus() {
       const view = editorViewRef.current
-      if (!view) return
+      if (!view) {
+        sourceRef.current?.focus()
+        return
+      }
       view.focus()
     },
     getMarkdown() {
       const editor = editorRef.current
-      if (!editor) return null
+      // Source mode (or before init): the textarea text is the source of truth.
+      if (!editor) return markdownRef.current
       let md = null
       editor.action((ctx) => {
         const view = ctx.get(editorViewCtx)
         md = ctx.get(serializerCtx)(view.state.doc)
       })
+      markdownRef.current = md
       return md
     },
   }), [])
 
   useEffect(() => {
+    // Source mode renders a plain textarea instead — no Milkdown to build.
+    if (sourceMode) return
     if (!containerRef.current) return
 
     let cancelled = false
@@ -843,7 +882,9 @@ const Editor = forwardRef(function Editor({ defaultValue = '', onChange, onDrawi
       const editor = await MilkdownEditor.make()
         .config((ctx) => {
           ctx.set(rootCtx, containerRef.current)
-          ctx.set(defaultValueCtx, defaultValue)
+          // Seed from the live markdown (so toggling back from source mode keeps
+          // edits), falling back to the initial prop on first mount.
+          ctx.set(defaultValueCtx, markdownRef.current ?? defaultValue)
           ctx.get(listenerCtx).markdownUpdated((_ctx, markdown) => {
             // Skip parent state updates while IME composition is active —
             // the React re-render they trigger can interrupt composition on
@@ -851,6 +892,7 @@ const Editor = forwardRef(function Editor({ defaultValue = '', onChange, onDrawi
             // compositionend, which fires the listener again with the
             // committed text, so no input is lost.
             if (editorViewRef.current?.composing) return
+            markdownRef.current = markdown
             onChangeRef.current?.(markdown)
           })
           let slashMenuView = null
@@ -905,10 +947,11 @@ const Editor = forwardRef(function Editor({ defaultValue = '', onChange, onDrawi
         containerRef.current.innerHTML = ''
       }
     }
-  }, [])
+  }, [sourceMode])
 
   // Image paste handler
   useEffect(() => {
+    if (sourceMode) return
     const container = containerRef.current
     if (!container) return
 
@@ -944,10 +987,62 @@ const Editor = forwardRef(function Editor({ defaultValue = '', onChange, onDrawi
 
     container.addEventListener('paste', handlePaste)
     return () => container.removeEventListener('paste', handlePaste)
-  }, [])
+  }, [sourceMode])
+
+  const handleSourceChange = (e) => {
+    const v = e.target.value
+    markdownRef.current = v
+    setSourceText(v)
+    onChangeRef.current?.(v)
+  }
+
+  const toggleSourceMode = () => {
+    const goingToSource = !sourceMode
+    if (goingToSource) {
+      // Capture live markdown from Milkdown before it's torn down so the
+      // textarea opens on exactly what's on screen.
+      const editor = editorRef.current
+      let md = markdownRef.current
+      if (editor) {
+        editor.action((ctx) => {
+          const view = ctx.get(editorViewCtx)
+          md = ctx.get(serializerCtx)(view.state.doc)
+        })
+      }
+      markdownRef.current = md ?? ''
+      setSourceText(md ?? '')
+    }
+    // source -> wysiwyg needs no capture: markdownRef already holds the
+    // textarea text, and the init effect re-seeds Milkdown from it.
+    try {
+      localStorage.setItem(SOURCE_MODE_KEY, goingToSource ? '1' : '0')
+    } catch { /* ignore */ }
+    setSourceMode(goingToSource)
+  }
 
   return (
-    <div className="milkdown" ref={containerRef} />
+    <div className="milkdown-shell">
+      <button
+        type="button"
+        className="editor-mode-toggle"
+        onClick={toggleSourceMode}
+        title={sourceMode ? t('editor.switchToRichText') : t('editor.switchToSource')}
+      >
+        {sourceMode ? t('editor.switchToRichText') : t('editor.switchToSource')}
+      </button>
+      {sourceMode ? (
+        <textarea
+          ref={sourceRef}
+          className="editor-source"
+          value={sourceText}
+          onChange={handleSourceChange}
+          placeholder={t('editor.sourcePlaceholder')}
+          spellCheck={false}
+        />
+      ) : (
+        <div className="milkdown" ref={containerRef} />
+      )}
+    </div>
   )
 })
 
diff --git a/frontend/src/index.css b/frontend/src/index.css
index a59db79..20f5e07 100644
--- a/frontend/src/index.css
+++ b/frontend/src/index.css
@@ -193,6 +193,46 @@ code, kbd, samp, pre,
 }
 
 /* Milkdown editor styles */
+.milkdown-shell {
+  position: relative;
+}
+
+.editor-mode-toggle {
+  position: absolute;
+  top: 0.5rem;
+  right: 0.5rem;
+  z-index: 10;
+  font-size: 0.75rem;
+  padding: 0.2rem 0.6rem;
+  border: 1px solid var(--color-border);
+  border-radius: 6px;
+  background: var(--color-surface);
+  color: var(--color-text-secondary);
+  cursor: pointer;
+  opacity: 0.7;
+}
+.editor-mode-toggle:hover {
+  background: var(--color-surface-hover);
+  color: var(--color-text);
+  opacity: 1;
+}
+
+.editor-source {
+  width: 100%;
+  min-height: 400px;
+  padding: 1rem;
+  border: none;
+  outline: none;
+  resize: vertical;
+  background: transparent;
+  color: var(--color-text);
+  font-family: var(--font-mono);
+  font-size: 0.9rem;
+  line-height: 1.6;
+  white-space: pre-wrap;
+  word-break: break-word;
+}
+
 .milkdown .editor {
   outline: none;
   padding: 1rem;
diff --git a/frontend/src/locales/en.json b/frontend/src/locales/en.json
index 5672d9c..95e3bda 100644
--- a/frontend/src/locales/en.json
+++ b/frontend/src/locales/en.json
@@ -359,6 +359,11 @@
       "media": { "label": "Media Library", "desc": "Pick from uploaded files" }
     }
   },
+  "editor": {
+    "switchToSource": "Edit source (Markdown)",
+    "switchToRichText": "Rich text editor",
+    "sourcePlaceholder": "Write Markdown here..."
+  },
   "tableTooltip": {
     "addRowAbove": "Insert row above",
     "addRowBelow": "Insert row below",
diff --git a/frontend/src/locales/ja.json b/frontend/src/locales/ja.json
index 6dcec2e..84d23aa 100644
--- a/frontend/src/locales/ja.json
+++ b/frontend/src/locales/ja.json
@@ -359,6 +359,11 @@
       "media": { "label": "メディアライブラリ", "desc": "アップロード済みのファイルから選択" }
     }
   },
+  "editor": {
+    "switchToSource": "ソースを編集 (Markdown)",
+    "switchToRichText": "リッチテキストエディタ",
+    "sourcePlaceholder": "Markdown を入力..."
+  },
   "tableTooltip": {
     "addRowAbove": "上に行を挿入",
     "addRowBelow": "下に行を挿入",
diff --git a/frontend/src/locales/ko.json b/frontend/src/locales/ko.json
index ae5904f..cc1e608 100644
--- a/frontend/src/locales/ko.json
+++ b/frontend/src/locales/ko.json
@@ -359,6 +359,11 @@
       "media": { "label": "미디어 라이브러리", "desc": "업로드된 파일에서 선택" }
     }
   },
+  "editor": {
+    "switchToSource": "소스 편집 (Markdown)",
+    "switchToRichText": "리치 텍스트 편집기",
+    "sourcePlaceholder": "Markdown 입력..."
+  },
   "tableTooltip": {
     "addRowAbove": "위에 행 삽입",
     "addRowBelow": "아래에 행 삽입",
diff --git a/frontend/src/locales/zh-TW.json b/frontend/src/locales/zh-TW.json
index 9551e91..91bda38 100644
--- a/frontend/src/locales/zh-TW.json
+++ b/frontend/src/locales/zh-TW.json
@@ -359,6 +359,11 @@
       "media": { "label": "媒體庫", "desc": "從已上傳檔案中選擇" }
     }
   },
+  "editor": {
+    "switchToSource": "編輯原始碼 (Markdown)",
+    "switchToRichText": "所見即所得編輯器",
+    "sourcePlaceholder": "在此輸入 Markdown..."
+  },
   "tableTooltip": {
     "addRowAbove": "上方插入列",
     "addRowBelow": "下方插入列",