initial deploy

.dockerignore

@@ -0,0 +1,18 @@
+# 敏感資料（絕對不能上傳）
+.env
+firebase_key.json
+
+# Python 快取
+__pycache__/
+*.pyc
+*.pyo
+
+# 開發工具
+.vscode/
+.idea/
+*.ipynb
+
+# 其他
+other/
+*.docx
+*.pdf

.gitattributes

@@ -0,0 +1,40 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text
+*.png filter=lfs diff=lfs merge=lfs -text
+*.jpg filter=lfs diff=lfs merge=lfs -text
+*.jpeg filter=lfs diff=lfs merge=lfs -text
+*.svg filter=lfs diff=lfs merge=lfs -text
+*.gif filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,18 @@
+# 敏感資料（絕對不能上傳）
+.env
+firebase_key.json
+
+# Python 快取
+__pycache__/
+*.pyc
+*.pyo
+
+# 開發工具
+.vscode/
+.idea/
+*.ipynb
+
+# 其他
+other/
+*.docx
+*.pdf

Dockerfile

@@ -0,0 +1,20 @@
+FROM python:3.11-slim
+
+# 設定工作目錄
+WORKDIR /app
+
+# 先安裝依賴（利用 Docker layer cache，只有 requirements.txt 改變才重建）
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# 複製專案檔案（.dockerignore 會排除 .env、firebase_key.json）
+COPY . .
+
+# HF Spaces 要求 port 7860
+EXPOSE 7860
+
+# 用 gunicorn 啟動，timeout 調高因為 build pipeline 需要時間
+CMD ["gunicorn", "app:server", \
+     "--bind", "0.0.0.0:7860", \
+     "--timeout", "120", \
+     "--workers", "1"]

README.md

@@ -0,0 +1,10 @@
+---
+title: Dash-math Database
+emoji: ⚡
+colorFrom: pink
+colorTo: pink
+sdk: docker
+pinned: false
+---
+
+Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

app.py

@@ -0,0 +1,128 @@
+"""
+app.py
+------
+Dash app 進入點。
+
+職責（僅此而已）：
+    1. 建立 Dash app 實例
+    2. 組裝 AppShell layout
+    3. 掛載全域 callback（navbar、主題、MathJax）
+    4. 啟動 dev server
+
+Build pipeline（MD → JSON）已移至 build.py。
+  - 若希望每次啟動都重建：取消下方 build_if_needed 的 force=True 呼叫
+  - 若只想手動重建：直接執行 python build.py --force
+"""
+
+import dash
+from dash import Dash, html, dcc
+from dash import Input, Output, clientside_callback
+import dash_mantine_components as dmc
+from pathlib import Path
+
+from layout.shell.navbar    import generate_navbar
+from layout.shell.header    import generate_header
+from layout.shell.main      import generate_main
+from layout.shell.footer    import generate_footer
+from layout.shell.callbacks import generate_toggle_navbar, switch_light_dark
+
+# 確保頁面 section 切換 callback 在啟動時就被註冊
+import layout.page.page_callbacks  # noqa: F401
+
+# 學生登入元件
+from student_login import create_student_store, create_login_modal, create_student_badge
+
+# Firebase quiz hooks（答題記錄）
+from firebase_quiz_hooks import create_dummy_stores
+import firebase_quiz_hooks  # noqa: F401 ← 掛載 callback
+
+# Session 狀態保存（重整後恢復 section、答題、解法）由 assets/session_state.js 處理
+from session_state import create_session_stores
+
+# Build pipeline：只在啟動時呼叫，不影響 app 本體邏輯
+from build import build_if_needed
+
+BASE_DIR    = Path(__file__).resolve().parent
+CONFIG_PATH = BASE_DIR / "paths.json"
+
+build_if_needed(CONFIG_PATH, force=False)  # 只重建比 .md 新的 JSON，加速啟動
+
+# ---------------------------------------------------------------------------
+# App 實例
+# ---------------------------------------------------------------------------
+app = Dash(
+    __name__,
+    use_pages=True,
+    external_stylesheets=dmc.styles.ALL,
+    suppress_callback_exceptions=True,
+)
+
+# ---------------------------------------------------------------------------
+# Callbacks
+# ---------------------------------------------------------------------------
+generate_toggle_navbar()
+switch_light_dark()
+
+# ---------------------------------------------------------------------------
+# Layout 元件
+# ---------------------------------------------------------------------------
+header = generate_header()
+navbar = generate_navbar()
+main   = generate_main()
+footer = generate_footer()
+
+layout = dmc.AppShell(
+    id="appshell",
+    children=[
+        dcc.Store(id="noop-store"),
+        html.Div(id="theme-dummy", style={"display": "none"}),
+
+        # ── 學生登入相關 ──
+        create_student_store(),       # localStorage 學號 Store
+        create_login_modal(),         # 學號輸入 Modal
+        *create_dummy_stores(),       # Firebase 虛擬 Store
+        *create_session_stores(),     # Session 狀態 Store
+
+        header, navbar, main, footer,
+    ],
+    header={"height": "4rem"},
+    navbar={
+        "width": {"xs": 200, "sm": 250, "md": 300, "lg": 300},
+        "breakpoint": "sm",
+        "collapsed": {"mobile": True, "desktop": False},
+    },
+    footer={"height": "2rem"},
+    padding="lg",
+)
+
+app.layout = dmc.MantineProvider(
+    id="mantine-provider",
+    children=layout,
+    defaultColorScheme="light",
+)
+
+# ---------------------------------------------------------------------------
+# MathJax：每次換頁都重新 typeset
+# ---------------------------------------------------------------------------
+clientside_callback(
+    """
+    function(pathname) {
+        if (window.MathJax) {
+            window.MathJax.typeset();
+        }
+        return "";
+    }
+    """,
+    Output("noop-store", "data"),
+    Input("_pages_location", "pathname"),
+)
+
+# ---------------------------------------------------------------------------
+# 啟動
+# ---------------------------------------------------------------------------
+server = app.server  # 給 gunicorn 用：gunicorn app:server
+
+if __name__ == "__main__":
+    app.run(debug=True)
+    # 部署時改用：
+    # app.run(host="0.0.0.0", port=8050, debug=False)

assets/anchor-scroll.js

@@ -0,0 +1,43 @@
+(function () {
+  function cleanIdFromHash(h) {
+    if (!h) return "";
+    var s = h.replace(/^#/, "");
+    if (s.startsWith("h-")) s = s.slice(2);
+    return s;
+  }
+
+  function scrollToId(id) {
+    if (!id) return;
+    var el = document.getElementById(id);
+    if (!el) return;
+    // ?? CSS ? scroll-margin-top??????? header ??
+    el.scrollIntoView({ behavior: "smooth", block: "start", inline: "nearest" });
+  }
+
+  // 1) ??? #hash ?????????????
+  window.addEventListener("load", function () {
+    var id = cleanIdFromHash(location.hash);
+    if (id) setTimeout(function(){ scrollToId(id); }, 0);
+  });
+
+  // 2) hash ????? pushState ??????
+  window.addEventListener("hashchange", function () {
+    var id = cleanIdFromHash(location.hash);
+    if (id) scrollToId(id);
+  });
+
+  // 3) ?????? #fragment ???????????
+  document.addEventListener("click", function (e) {
+    var a = e.target.closest('a[href^="#"]');
+    if (!a) return;
+    var raw = a.getAttribute("href") || "";
+    var id  = cleanIdFromHash(raw);
+    if (!id) return;        // ?????????????????
+    var el = document.getElementById(id);
+    if (!el) return;        // ???????
+    e.preventDefault();
+    scrollToId(id);
+    // ???? hash?????????
+    history.pushState(null, "", "#" + id);
+  });
+})();

assets/ggb.css

@@ -0,0 +1,10 @@
+/* 把任何誤蓋在 ggb-wrap 上的透明層都失效 */
+.ggb-wrap * {
+  pointer-events: auto;
+}
+.ggb-wrap::before {
+  content: "";
+  position: absolute;
+  inset: 0;
+  pointer-events: none; /* 確保沒有匿名覆蓋層攔截 */
+}

assets/mathjax-plotly.js

@@ -0,0 +1,36 @@
+// assets/mathjax-plotly.js
+(function () {
+  function attachListeners() {
+    function typeset(target) {
+      try {
+        if (window.MathJax) {
+          // v3
+          if (typeof window.MathJax.typesetPromise === "function") {
+            return window.MathJax.typesetPromise([target || document.body]);
+          }
+          // v2
+          if (window.MathJax.Hub && typeof window.MathJax.Hub.Queue === "function") {
+            window.MathJax.Hub.Queue(["Typeset", window.MathJax.Hub, target || document.body]);
+          }
+        }
+      } catch (e) {
+        console.warn("MathJax typeset failed:", e);
+      }
+    }
+
+    document.addEventListener("plotly_afterplot", function (e) { typeset(e.target); });
+    document.addEventListener("plotly_relayout",  function (e) { typeset(e.target); });
+    document.addEventListener("plotly_redraw",   function (e) { typeset(e.target); });
+    window.addEventListener("load", function () { typeset(document.body); });
+  }
+
+  // 如果已經有 MathJax，就只掛事件
+  if (window.MathJax) { attachListeners(); return; }
+
+  // 推薦載 v3（tex-svg 渲染器）；載完再掛事件
+  var s = document.createElement("script");
+  s.src = "https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-svg.js";
+  s.defer = true;
+  s.onload = attachListeners;
+  document.head.appendChild(s);
+})();

assets/quiz.css

@@ -0,0 +1,105 @@
+/* ? Radio ?????????????? */
+.quiz-option .mantine-Radio-body {
+  display: flex;
+  align-items: center; /* ?????? flex-start????????? */
+}
+
+/* ????????????????? flex ?? */
+.quiz-option .mantine-Radio-label {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;          /* ?? Python ? inline-flex ? gap ?? */
+}
+
+
+
+
+/* ???????????????????? marker */
+.math-ol {
+  counter-reset: mathitem;
+  list-style: none;       /* ???????? 1. 2. 3. */
+  margin-left: 1.5rem;    /* ????????? */
+  padding-left: 0;
+}
+
+.math-ol > li {
+  counter-increment: mathitem;
+  display: flex;
+  align-items: center;    /* ????????????????????? */
+  gap: 0.5rem;            /* ?????????? */
+}
+
+/* ????? marker */
+.math-ol > li::before {
+  content: counter(mathitem) ".";
+  flex: 0 0 auto;
+  min-width: 1.5rem;      /* ???????????? */
+  text-align: right;
+}
+
+/* ?????? marker ??????????????????? */
+
+/* ?? ListItem??????marker + ?? */
+.mantine-List-item.themed-color {
+  display: flex;
+  align-items: center;      /* marker ????????? */
+}
+
+/* ??? span ?????????? "1." "2." ?? marker */
+.mantine-List-item.themed-color > span:first-child {
+  position: static !important;   /* ? render_list ?? absolute ?? */
+  left: auto !important;
+  top: auto !important;
+  transform: none !important;
+
+  min-width: 1.8rem;            /* ???????????? */
+  text-align: right;
+  margin-right: 0.5rem;
+}
+
+/* ??? div ????????????? */
+.mantine-List-item.themed-color > div:last-child {
+  flex: 1 1 auto;
+}
+
+
+/* 讓數學式的顏色跟外層 .themed-color 一樣 */
+.themed-color .katex,
+.themed-color .katex * {
+  color: inherit;
+}
+
+
+/* 只調整 \text{} 的字型，跟主題 body font 一致 */
+.katex .text,
+.katex .text * {
+  font-family: var(--mantine-font-family, system-ui, -apple-system,
+                   BlinkMacSystemFont, "Segoe UI", sans-serif);
+  font-weight: 400;
+}
+
+
+/* 讓數學式整體跟隨主題色 */
+.themed-color .katex {
+  color: inherit !important;
+}
+
+/* 特別是 \text{...} 產生的文字 span */
+.themed-color .katex .text,
+.themed-color .katex .mord.text,
+.themed-color .katex .mathnormal {
+  color: inherit !important;
+}
+
+
+/* 只調整 KaTeX 裡 \text{} 的字型與大小 */
+.katex .text,
+.katex .mord.text,
+.katex .text * {
+  font-family: var(--mantine-font-family,
+                   system-ui, -apple-system, BlinkMacSystemFont,
+                   "Segoe UI", "Microsoft JhengHei", sans-serif) !important;
+  font-size: 0.9em !important;   /* 比周圍數學略小一點，自己可改 0.8em / 1em */
+  font-weight: 400;              /* 回到正常粗細 */
+  font-style: normal;            /* 不要斜體就設 normal */
+}

assets/scroll.css

@@ -0,0 +1,104 @@
+html {
+  scroll-behavior: smooth;     /* 平滑滾動 */
+}
+
+/* heading 的捲動預留空間（依你的 header 高度調整，如 80~100px） */
+[id^="h-"] {
+  scroll-margin-top: 90px;
+}
+/* 固定 AppShell Header 在頂部，並有底色與層級 */
+.mantine-AppShell-header{
+  position: sticky;
+  top: 0;
+  z-index: 2000;
+  background: var(--mantine-color-body);
+  border-bottom: 1px solid var(--mantine-color-default-border);
+}
+
+/* 主內容預留 Header 高度（64px） */
+.mantine-AppShell-main{
+  padding-top: 64px;
+}
+
+/* 圖片安全預設 */
+img{ max-width: 100%; height: auto; }
+
+html[data-mantine-color-scheme="light"] .themed-color,
+#mantine-provider[data-mantine-color-scheme="light"] .themed-color { 
+  --tc: var(--tc-light);
+}
+
+html[data-mantine-color-scheme="dark"] .themed-color,
+#mantine-provider[data-mantine-color-scheme="dark"]  .themed-color { 
+  --tc: var(--tc-dark);
+}
+
+/* 讓 --tc 指向 light 或 dark，以 data-mantine-color-scheme 為準 */
+[data-mantine-color-scheme="light"] .themed-color { --tc: var(--tc-light); }
+[data-mantine-color-scheme="dark"]  .themed-color { --tc: var(--tc-dark); }
+
+/* === Math blocks center (KaTeX + MathJax) === */
+.katex-display {
+  text-align: center;
+  overflow-x: auto;      /* 數學式太長時橫向捲動，不截斷 */
+  overflow-y: hidden;
+  padding-bottom: 4px;   /* 捲動條不擋到數學式 */
+}
+mjx-container[display="true"] {
+  display: block;
+  text-align: center;
+  margin: 8px 0;
+  overflow-x: auto;      /* MathJax 同樣加橫向捲動 */
+}
+
+
+.math-block { display:block; width:100%; text-align:center; }
+
+.mantine-List-item .math-block {
+  width: calc(100% + var(--li-outdent, 0px));
+  margin-left: calc(-1 * var(--li-outdent, 0px));
+}
+
+/* 主題色切換：背景與前景 */
+html[data-mantine-color-scheme="light"] .themed-bg { --bg: var(--bg-light); }
+html[data-mantine-color-scheme="dark"]  .themed-bg { --bg: var(--bg-dark);  }
+html[data-mantine-color-scheme="light"] .themed-fg { --fg: var(--fg-light); }
+html[data-mantine-color-scheme="dark"]  .themed-fg { --fg: var(--fg-dark);  }
+
+/* 讓有這兩個 class 的元素吃到背景/字色 */
+.themed-bg { background: var(--bg, var(--bg-light)); }
+.themed-fg { color:      var(--fg, var(--fg-light)); }
+
+/* === 讓顏色標記（<!--c_xxx-->）真的套到文字上 === */
+.themed-color { color: var(--tc, inherit); }
+
+
+
+/* === 卡片用的背景/前景變數（若尚未加入）=== */
+html[data-mantine-color-scheme="light"] .themed-bg { --bg: var(--bg-light); }
+html[data-mantine-color-scheme="dark"]  .themed-bg { --bg: var(--bg-dark); }
+.themed-bg { background: var(--bg, transparent); }
+
+html[data-mantine-color-scheme="light"] .themed-fg { --fg: var(--fg-light); }
+html[data-mantine-color-scheme="dark"]  .themed-fg { --fg: var(--fg-dark); }
+.themed-fg { color: var(--fg, inherit); }
+
+/* 統一卡片外殼造型 */
+.card-shell {
+  overflow: visible;              /* 改為 visible，避免截斷長數學式 */
+  border-radius: var(--mantine-radius-md);
+}
+
+/* 亮色：維持無外框 */
+html[data-mantine-color-scheme="light"] .card-shell {
+  border: 0;
+  box-shadow: none;
+}
+
+/* 暗色：加一圈白色外框（半透明） */
+html[data-mantine-color-scheme="dark"] .card-shell {
+  border: 1px solid rgba(255, 255, 255, 0.28);  /* 想更亮改 0.4、更細可用 0.22 */
+  box-shadow: none;                             /* 不要陰影 */
+}
+
+

assets/session_state.js

@@ -0,0 +1,171 @@
+/**
+ * session_state.js
+ * 事件驅動版，不做定時掃描，只在互動時儲存。
+ */
+(function () {
+    "use strict";
+
+    var STORE_KEY = "dash_math_page_state";
+
+    function loadState() {
+        try { return JSON.parse(sessionStorage.getItem(STORE_KEY) || "{}"); }
+        catch (e) { return {}; }
+    }
+    function saveState(s) {
+        try { sessionStorage.setItem(STORE_KEY, JSON.stringify(s)); }
+        catch (e) {}
+    }
+    function getPathname() { return window.location.pathname || "/"; }
+
+    function saveProp(key, value) {
+        var s = loadState(), p = getPathname();
+        if (!s[p]) s[p] = {};
+        s[p][key] = value;
+        saveState(s);
+    }
+    function saveNested(group, key, value) {
+        var s = loadState(), p = getPathname();
+        if (!s[p]) s[p] = {};
+        if (!s[p][group]) s[p][group] = {};
+        s[p][group][key] = value;
+        saveState(s);
+    }
+    function getPs() {
+        var s = loadState(), p = getPathname();
+        return s[p] || {};
+    }
+
+    // ── 恢復 ──────────────────────────────────────────────────────────────
+
+    var _restoring = false;
+
+    function restoreState() {
+        var ps = getPs();
+        _restoring = true;
+
+        // Section
+        if (ps.section) {
+            var b = document.querySelector('[data-sid="' + ps.section + '"]');
+            if (b) b.click();
+        }
+
+        // 填空題
+        var inputs = ps.quiz_inputs || {};
+        Object.keys(inputs).forEach(function (qid) {
+            var val = inputs[qid];
+            if (!val) return;
+            // 用 querySelectorAll 找包含此 qid 的 input
+            document.querySelectorAll("input").forEach(function (el) {
+                var w = el.closest("[id]");
+                if (!w || w.id.indexOf(qid) === -1 || w.id.indexOf("quiz-input") === -1) return;
+                var setter = Object.getOwnPropertyDescriptor(window.HTMLInputElement.prototype, "value").set;
+                setter.call(el, val);
+                el.dispatchEvent(new Event("input", { bubbles: true }));
+            });
+        });
+
+        // 解法展開
+        var solutions = ps.solutions || {};
+        Object.keys(solutions).forEach(function (key) {
+            if (!solutions[key]) return;
+            document.querySelectorAll("button").forEach(function (btn) {
+                if (btn.id && btn.id.indexOf(key) > -1 && btn.id.indexOf("solution-toggle") > -1) {
+                    btn.click();
+                }
+            });
+        });
+
+        setTimeout(function () { _restoring = false; }, 800);
+    }
+
+    // ── 掛載監聽 ─────────────────────────────────────────────────────────
+
+    var _attached = new Set();
+
+    function attachListeners() {
+        // Section 按鈕
+        document.querySelectorAll("[data-sid]").forEach(function (btn) {
+            var sid = btn.getAttribute("data-sid");
+            if (_attached.has("s:" + sid)) return;
+            _attached.add("s:" + sid);
+            btn.addEventListener("click", function () {
+                if (!_restoring) saveProp("section", sid);
+            });
+        });
+
+        // 填空題 input
+        document.querySelectorAll("input").forEach(function (el) {
+            if (_attached.has(el)) return;
+            var w = el.closest("[id]");
+            if (!w || !w.id || w.id.indexOf("quiz-input") === -1) return;
+            var m = w.id.match(/"qid":"([^"]+)"/);
+            if (!m) return;
+            var qid = m[1];
+            _attached.add(el);
+            el.addEventListener("change", function () {
+                if (!_restoring) saveNested("quiz_inputs", qid, el.value);
+            });
+        });
+
+        // 解法 toggle 按鈕
+        document.querySelectorAll("button").forEach(function (btn) {
+            if (_attached.has(btn)) return;
+            if (!btn.id || btn.id.indexOf("solution-toggle") === -1) return;
+            var m = btn.id.match(/"key":"([^"]+)"/);
+            if (!m) return;
+            var key = m[1];
+            _attached.add(btn);
+            btn.addEventListener("click", function () {
+                if (_restoring) return;
+                // 延遲判斷是否展開
+                setTimeout(function () {
+                    var col = document.querySelector('[id*="' + key + '"][id*="solution-collapse"]');
+                    var opened = col ? col.offsetHeight > 10 : false;
+                    saveNested("solutions", key, opened);
+                }, 400);
+            });
+        });
+    }
+
+    // ── 換頁偵測 ─────────────────────────────────────────────────────────
+
+    var _lastPath = null, _timer = null;
+
+    function checkPath() {
+        var cur = getPathname();
+        if (cur !== _lastPath) {
+            _lastPath = cur;
+            _attached.clear();
+            clearTimeout(_timer);
+            _timer = setTimeout(function () {
+                attachListeners();
+                restoreState();
+            }, 900);
+        } else {
+            attachListeners();
+        }
+    }
+
+    // MutationObserver：只做 debounce checkPath，不掃描整個 DOM
+    var _mutTimer = null;
+    var obs = new MutationObserver(function () {
+        clearTimeout(_mutTimer);
+        _mutTimer = setTimeout(checkPath, 200);
+    });
+
+    function init() {
+        _lastPath = getPathname();
+        obs.observe(document.body, { childList: true, subtree: false }); // subtree:false 減少觸發
+        setTimeout(function () {
+            attachListeners();
+            restoreState();
+        }, 1000);
+    }
+
+    if (document.readyState === "loading") {
+        document.addEventListener("DOMContentLoaded", init);
+    } else {
+        init();
+    }
+
+})();

assets/toc.css

@@ -0,0 +1,125 @@
+/* === TOC 區塊：捲動與底部空白 === */
+
+:root {
+  --toc-bottom-gap: 10px;
+}
+
+/* TOC 欄：sticky 定位，高度跟隨視窗 */
+.toc-col-wrapper {
+  /* 桌機：顯示 */
+  display: block;
+}
+
+/* 內層容器：只負責間距，overflow 由外層 sticky 容器管理 */
+.toc-scroll {
+  padding-right: 4px;
+  padding-bottom: var(--toc-bottom-gap);
+}
+
+/* 再塞一塊看不見的空白，讓最後一個項目可以捲到按鈕上方 */
+.toc-scroll::after {
+  content: "";
+  display: block;
+  height: var(--toc-bottom-gap);
+}
+
+/* === TOC 連結 / 按鈕 顏色設定 === */
+
+/* 淺色主題 */
+.toc-container .toc-link,
+.toc-container .toc-link:link,
+.toc-container .toc-link:visited,
+.toc-container .toc-link:active,
+.toc-container .toc-button {
+  color: #228be6 !important;
+  text-decoration: none !important;
+}
+
+/* 淺色主題 hover / active */
+.toc-container .toc-link:hover,
+.toc-container .toc-button:hover,
+.toc-container .toc-button:active,
+.toc-container .toc-button:focus,
+.toc-container .toc-button[data-active="true"] {
+  color: #228be6 !important;
+  background-color: transparent !important;
+  box-shadow: none !important;
+}
+
+/* 深色主題 */
+[data-mantine-color-scheme="dark"] .toc-container .toc-link,
+[data-mantine-color-scheme="dark"] .toc-container .toc-link:link,
+[data-mantine-color-scheme="dark"] .toc-container .toc-link:visited,
+[data-mantine-color-scheme="dark"] .toc-container .toc-link:active,
+[data-mantine-color-scheme="dark"] .toc-container .toc-button {
+  color: #b197fc !important;
+}
+
+[data-mantine-color-scheme="dark"] .toc-container .toc-link:hover,
+[data-mantine-color-scheme="dark"] .toc-container .toc-button:hover,
+[data-mantine-color-scheme="dark"] .toc-container .toc-button:active,
+[data-mantine-color-scheme="dark"] .toc-container .toc-button:focus,
+[data-mantine-color-scheme="dark"] .toc-container .toc-button[data-active="true"] {
+  color: #b197fc !important;
+  background-color: transparent !important;
+  box-shadow: none !important;
+}
+
+/* TOC 內所有超連結都不要底線 */
+.toc-scroll a,
+.toc-scroll a:link,
+.toc-scroll a:visited,
+.toc-scroll a:hover,
+.toc-scroll a:active {
+  text-decoration: none !important;
+}
+
+/* 目前閱讀的段落在 TOC 上高亮 */
+.toc-item.toc-active .mantine-Button-root {
+  font-weight: 600;
+  border-left: 3px solid var(--mantine-color-teal-6);
+  padding-left: 10px;
+  background-color: rgba(56, 178, 172, 0.08);
+}
+
+/* 讓目錄按鈕的文字可以換行 */
+.toc-button {
+  white-space: normal;
+  height: auto;
+  line-height: 1.4;
+}
+
+.toc-button .mantine-Button-label {
+  white-space: normal;
+  text-align: left;
+  overflow: visible;
+  text-overflow: clip;
+}
+
+/* ===================================================================
+   響應式：小螢幕隱藏 TOC
+   =================================================================== */
+
+/* < 768px：隱藏 TOC，主內容全寬 */
+@media (max-width: 768px) {
+  .toc-col-wrapper {
+    display: none !important;
+  }
+}
+
+/* 768px ~ 992px：顯示但縮小 */
+@media (min-width: 769px) and (max-width: 992px) {
+  .toc-scroll {
+    max-height: calc(100vh - 140px);
+  }
+}
+
+/* ===================================================================
+   視窗過小（縮放超過 125%）時也隱藏 TOC
+   依據實際視窗寬度，非 CSS zoom
+   =================================================================== */
+@media (max-width: 900px) {
+  .toc-col-wrapper {
+    display: none !important;
+  }
+}

assets/toc_scrollspy.js

@@ -0,0 +1,119 @@
+// assets/toc_scrollspy.js
+console.log("[toc_scrollspy] loaded (v3-scroll-sync)");
+
+(function () {
+  let ticking = false;
+
+  function getTocState() {
+    const root = document.getElementById("toc-root");
+    if (!root) return null;
+
+    const offset = parseInt(root.dataset.tocOffset || "80", 10);
+    const items = Array.from(root.querySelectorAll(".toc-item"));
+    if (!items.length) return null;
+
+    const pairs = items
+      .map((item) => {
+        const targetId = item.dataset.target;
+        if (!targetId) return null;
+        const el = document.getElementById(targetId);
+        if (!el) return null;
+        return { item, el, id: targetId };
+      })
+      .filter(Boolean);
+
+    if (!pairs.length) return null;
+
+    return { root, offset, pairs };
+  }
+
+  function keepItemVisible(root, item) {
+    if (!root || !item) return;
+
+    const rootTop = root.scrollTop;
+    const rootBottom = rootTop + root.clientHeight;
+
+    const itemTop = item.offsetTop;
+    const itemBottom = itemTop + item.offsetHeight;
+
+    if (itemTop < rootTop + 8) {
+      root.scrollTo({
+        top: Math.max(0, itemTop - 8),
+        behavior: "smooth",
+      });
+    } else if (itemBottom > rootBottom - 8) {
+      root.scrollTo({
+        top: itemBottom - root.clientHeight + 8,
+        behavior: "smooth",
+      });
+    }
+  }
+
+  function updateActiveToc() {
+    const state = getTocState();
+    if (!state) return;
+
+    const { root, offset, pairs } = state;
+
+    // 找目前最接近視窗頂端 offset 的 section
+    let active = pairs[0];
+    let bestDist = Infinity;
+
+    for (const pair of pairs) {
+      const rect = pair.el.getBoundingClientRect();
+      const dist = Math.abs(rect.top - offset - 8);
+
+      // 優先選在 offset 上方或接近 offset 的 section
+      if (rect.top - offset <= 20 && dist < bestDist) {
+        bestDist = dist;
+        active = pair;
+      }
+    }
+
+    // 如果上面都沒找到，就退回第一個可見 section
+    if (!active) {
+      for (const pair of pairs) {
+        const rect = pair.el.getBoundingClientRect();
+        if (rect.top >= offset) {
+          active = pair;
+          break;
+        }
+      }
+    }
+
+    pairs.forEach(({ item }) => item.classList.remove("toc-active"));
+
+    if (active) {
+      active.item.classList.add("toc-active");
+      keepItemVisible(root, active.item);
+    }
+  }
+
+  function requestUpdate() {
+    if (ticking) return;
+    ticking = true;
+    window.requestAnimationFrame(() => {
+      updateActiveToc();
+      ticking = false;
+    });
+  }
+
+  function start() {
+    requestUpdate();
+
+    window.addEventListener("scroll", requestUpdate, { passive: true });
+    window.addEventListener("resize", requestUpdate, { passive: true });
+
+    const mo = new MutationObserver(() => {
+      requestUpdate();
+    });
+
+    mo.observe(document.body, { childList: true, subtree: true });
+  }
+
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", start);
+  } else {
+    start();
+  }
+})();

build.py

@@ -0,0 +1,66 @@
+"""
+build.py
+--------
+Markdown → JSON 的 build pipeline。
+
+職責：
+    讀取 paths.json → 對每個任務呼叫 Test2ChMd._export_one → 輸出 JSON
+
+與 app.py 完全解耦，可用兩種方式執行：
+
+  A. 命令列（手動重建）：
+        python build.py                        # 使用預設 paths.json
+        python build.py paths_ch15.json        # 指定 config
+        python build.py paths.json --force     # 強制重建全部
+
+  B. 由 app.py import 並在啟動時呼叫：
+        from build import build_if_needed
+        build_if_needed(CONFIG_PATH, force=False)  # 只重建有異動的任務
+"""
+
+from __future__ import annotations
+import sys
+from pathlib import Path
+
+# Test2ChMd 放在同層或 layout/ 下，依實際位置選一種
+from layout.converter.md_pipeline import build_from_config
+
+
+def build_if_needed(
+    config_path: str | Path = "paths.json",
+    *,
+    force: bool = False,
+) -> list[Path]:
+    """
+    執行 build pipeline。
+
+    config_path：paths.json 路徑（絕對或相對於 CWD）
+    force：True → 強制重建全部任務；False → 只重建比 md 舊的 json
+    """
+    return build_from_config(config_path, force=force)
+
+
+# ---------------------------------------------------------------------------
+# 命令列介面
+# ---------------------------------------------------------------------------
+if __name__ == "__main__":
+    import argparse
+
+    parser = argparse.ArgumentParser(
+        description="把 paths.json 中的 Markdown 轉換成 JSON"
+    )
+    parser.add_argument(
+        "config",
+        nargs="?",
+        default="paths.json",
+        help="paths.json 的路徑（預設：./paths.json）",
+    )
+    parser.add_argument(
+        "--force",
+        action="store_true",
+        help="強制重建全部任務（忽略 up_to_date 設定）",
+    )
+    args = parser.parse_args()
+
+    outputs = build_if_needed(args.config, force=args.force)
+    print(f"\n完成：共輸出 {len(outputs)} 個 JSON 檔案。")

components/__init__.py

@@ -0,0 +1,9 @@
+"""
+components/
+-----------
+純 UI 元件套件，所有元件均無 Dash callback 或 app 狀態。
+
+快速 import 範例：
+    from components.cards import create_chapter_card, render_card_from_node
+    from components.render_utils import _runs_to_children
+"""

components/cards.py

@@ -0,0 +1,283 @@
+"""
+components/cards.py
+--------------------
+所有卡片元件的單一來源。
+
+公開 API：
+    create_chapter_card(data)              → dmc.Card  （章節卡片，原 Chapter_card.py）
+    render_card_from_node(card_node)       → dmc.Card  （結構化 node 卡片，新版）
+    generate_custom_markdown_card(...)     → dmc.Card  （舊版 Markdown 字串卡片，保留供過渡期使用）
+
+遷移建議：
+    - 新頁面請使用 render_card_from_node（接受 JSON 結構化資料）
+    - generate_custom_markdown_card 標記為 deprecated，待舊頁面遷移完成後刪除
+"""
+
+from __future__ import annotations
+from typing import Any
+
+from dash import html, dcc
+import dash_mantine_components as dmc
+from dash_iconify import DashIconify
+
+from components.render_utils import _inline_math, _block_math, _runs_to_children
+
+try:
+    import dash_latex
+    DashLatex = dash_latex.DashLatex
+except Exception:
+    DashLatex = None
+
+
+# ---------------------------------------------------------------------------
+# 1. 章節卡片（原 Chapter_card.py）
+# ---------------------------------------------------------------------------
+
+def create_chapter_card(data: dict) -> dmc.Card:
+    """
+    產生章節總覽用的卡片。
+
+    data 欄位：
+        title       str         卡片標題
+        badges      List[Tuple[str, str]]  [(label, color), ...]
+        description List[str]   說明文字（最多 4 行）
+        link        str         「單元學習」按鈕連結
+        test        str         「小測驗」按鈕連結
+        trick       str (選用)  「技巧學習」按鈕連結
+    """
+    buttons = [
+        dmc.Anchor(
+            href=data["link"],
+            children=dmc.Button(
+                "單元學習", variant="light", color="orange", size="sm", radius="xl"
+            ),
+        )
+    ]
+
+    if "trick" in data:
+        buttons.append(
+            dmc.Anchor(
+                href=data["trick"],
+                children=dmc.Button(
+                    "技巧學習", variant="outline", color="gray", size="sm", radius="xl"
+                ),
+            )
+        )
+
+    buttons.append(
+        dmc.Anchor(
+            href=data["test"],
+            children=dmc.Button(
+                "小測驗", variant="filled", color="blue", size="sm", radius="xl"
+            ),
+        )
+    )
+
+    # 說明文字補足到 4 行，保持卡片高度一致
+    desc_items = [
+        dmc.Text(line, size="sm", c="dimmed") for line in data["description"]
+    ]
+    desc_items += [
+        dmc.Text(" ", size="sm")
+        for _ in range(4 - len(data["description"]))
+    ]
+
+    return dmc.Card(
+        children=[
+            dmc.Text(data["title"], fw=700, size="lg"),
+            dmc.Group(
+                gap="xs",
+                mt="xs",
+                mb="sm",
+                children=[
+                    dmc.Badge(label, color=color, radius="md")
+                    for label, color in data["badges"]
+                ],
+            ),
+            dmc.Stack(gap=0, style={"minHeight": 100}, children=desc_items),
+            dmc.Flex(
+                gap="sm",
+                wrap="wrap",
+                justify="flex-start",
+                mt="sm",
+                children=buttons,
+            ),
+        ],
+        withBorder=True,
+        shadow="sm",
+        radius="md",
+        style={
+            "width": {
+                "base": 280,
+                "sm": 320,
+                "md": 350,
+                "lg": 400,
+            }
+        },
+    )
+
+
+# ---------------------------------------------------------------------------
+# 2. 結構化 node 卡片（原 generate_common_card.py：render_card_from_node）
+# ---------------------------------------------------------------------------
+
+def render_card_from_node(card_node: dict) -> dmc.Card:
+    """
+    把 Test2ChMd 產生的卡片 JSON node 渲染成 DMC Card。
+
+    card_node 格式：
+        {
+            "kind":     str,          # 卡片種類（例如「定義」「定理」）
+            "headline": str,          # 標題文字
+            "body":     List[block],  # 內容 block 清單
+        }
+
+    body block 支援的 type：
+        paragraph / list / math / url / picture / horizontal_rule
+    """
+    kind = (card_node.get("kind") or "卡片").strip()
+    headline = (card_node.get("headline") or "").strip()
+
+    header = dmc.CardSection(
+        dmc.Group(
+            [
+                dmc.Badge(kind, color="violet", variant="filled"),
+                dmc.Text(headline, fw=700, style={"whiteSpace": "pre-wrap"}),
+            ],
+            gap="sm",
+        ),
+        withBorder=True,
+        inheritPadding=True,
+        py=6,
+        style={
+            "backgroundColor": dmc.DEFAULT_THEME["colors"]["violet"][7],
+            "color": "white",
+        },
+    )
+
+    body_children: list[Any] = []
+    for b in card_node.get("body", []):
+        t = (b.get("type") or "").lower()
+
+        if t == "paragraph":
+            body_children.append(
+                html.Div(_runs_to_children(b.get("runs") or []))
+            )
+        elif t == "list":
+            items = [
+                dmc.ListItem(_runs_to_children(it.get("runs") or []))
+                for it in b.get("content", [])
+            ]
+            body_children.append(
+                dmc.List(items, listStyleType="none", spacing="xs", withPadding=True)
+            )
+        elif t == "math":
+            body_children.append(_block_math(b.get("latex", "")))
+        elif t == "url":
+            body_children.append(
+                dcc.Markdown(
+                    f"[{b.get('text')}]({b.get('href')})", link_target="_blank"
+                )
+            )
+        elif t == "picture":
+            body_children.append(
+                html.Img(
+                    src=b.get("src"),
+                    title=b.get("alt") or "",
+                    style={
+                        "display": "inline-block",
+                        "margin": "6px",
+                        "maxWidth": "100%",
+                        "height": "auto",
+                    },
+                )
+            )
+        elif t == "horizontal_rule":
+            body_children.append(dmc.Divider(my=12))
+
+    return dmc.Card(
+        [header, dmc.Stack(body_children, gap="xs", px="md", py="sm")],
+        withBorder=True,
+        shadow="md",
+        radius="md",
+        mb=14,
+    )
+
+
+# ---------------------------------------------------------------------------
+# 3. 舊版 Markdown 字串卡片（deprecated，保留至頁面遷移完成）
+# ---------------------------------------------------------------------------
+
+def generate_custom_markdown_card(
+    title: str,
+    paragraphs: list[dict],
+    card_color: str = "#f8f9fa",
+    title_bg_color: str = dmc.DEFAULT_THEME["colors"]["green"][7],
+    latex_list: list[str] | None = None,
+) -> dmc.Card:
+    """
+    .. deprecated::
+        請改用 render_card_from_node。
+        此函式將在所有舊頁面遷移完成後刪除。
+
+    paragraphs 格式：
+        [{"text": str, "align": "left|center|right", "color": str}, ...]
+    latex_list 格式：
+        ["latex_str_1", "latex_str_2", ...]  （有序清單）
+    """
+    def _render_paragraph(p: dict) -> html.Div:
+        return html.Div(
+            dcc.Markdown(p["text"], mathjax=True),
+            style={
+                "textAlign": p.get("align", "left"),
+                "color": p.get("color", "black"),
+                "marginBottom": "0.5rem",
+            },
+        )
+
+    content: list[Any] = [_render_paragraph(p) for p in paragraphs]
+
+    if latex_list:
+        # 需要 dash_latex；若未安裝則退回純文字
+        list_items = []
+        for latex in latex_list:
+            if DashLatex:
+                list_items.append(
+                    dmc.ListItem(DashLatex(f"${latex}$"), mt=10)
+                )
+            else:
+                list_items.append(
+                    dmc.ListItem(dcc.Markdown(f"${latex}$", mathjax=True), mt=10)
+                )
+        content.append(
+            dmc.List(
+                children=list_items,
+                listStyleType="ordered",
+                spacing="sm",
+            )
+        )
+
+    return dmc.Card(
+        children=[
+            dmc.CardSection(
+                dmc.Group(
+                    children=[
+                        dmc.Text(
+                            title,
+                            fw=500,
+                            style={"color": dmc.DEFAULT_THEME["colors"]["gray"][0]},
+                        )
+                    ]
+                ),
+                withBorder=True,
+                inheritPadding=True,
+                py=3,
+                style={"backgroundColor": title_bg_color},
+            ),
+            html.Div(children=content, style={"padding": "10px"}),
+        ],
+        withBorder=True,
+        shadow="md",
+        radius="md",
+        style={"backgroundColor": card_color},
+    )

components/render_utils.py

@@ -0,0 +1,91 @@
+"""
+components/render_utils.py
+--------------------------
+純渲染工具函式，不依賴任何 Dash callback 或 app 狀態。
+供 cards.py、dashTest.py（未來統一後）等元件共用。
+
+公開 API：
+    _inline_math(latex, style=None)  → Dash element
+    _block_math(latex, style=None)   → Dash element
+    _runs_to_children(runs)          → List[Dash element]
+"""
+
+from __future__ import annotations
+from typing import Any
+
+from dash import html, dcc
+import dash_mantine_components as dmc
+
+try:
+    from dash_latex import DashLatex
+except Exception:
+    DashLatex = None
+
+
+# ---------------------------------------------------------------------------
+# 數學渲染
+# ---------------------------------------------------------------------------
+
+def _inline_math(latex: str, style: dict | None = None) -> Any:
+    """行內數學式。優先使用 DashLatex（KaTeX），退回 dcc.Markdown MathJax。"""
+    merged = {"display": "inline-block", "margin": "0 2px", **(style or {})}
+    if DashLatex:
+        return html.Span(DashLatex(latex, displayMode=False), style=merged)
+    src = latex if latex.strip().startswith("$") else f"${latex}$"
+    return dcc.Markdown(src, mathjax=True, style=merged)
+
+
+def _block_math(latex: str, style: dict | None = None) -> Any:
+    """區塊數學式。優先使用 DashLatex（KaTeX），退回 dcc.Markdown MathJax。"""
+    merged = {"margin": "8px 0", **(style or {})}
+    if DashLatex:
+        return html.Div(DashLatex(latex, displayMode=True), style=merged)
+    src = latex.strip()
+    if not (src.startswith("$$") and src.endswith("$$")):
+        src = f"$$\n{src}\n$$"
+    return dcc.Markdown(src, mathjax=True, style=merged)
+
+
+# ---------------------------------------------------------------------------
+# Run 列表轉 Dash 元素
+# ---------------------------------------------------------------------------
+
+def _runs_to_children(runs: list[dict] | None) -> list[Any]:
+    """
+    把 JSON block 中的 runs 陣列轉成 Dash 子元素清單。
+
+    Run 格式：
+        {"kind": "math", "latex": "..."}          → 行內數學
+        {"text": "...", "style": "bold|italic|bold-italic",
+         "color_light": "#xxx", "color_dark": "#xxx"}  → 文字 span
+    """
+    out: list[Any] = []
+    for r in runs or []:
+        # 數學 run
+        if r.get("kind") == "math" and "latex" in r:
+            out.append(_inline_math(r["latex"]))
+            continue
+
+        # 文字 run
+        sty: dict[str, Any] = {}
+        s = r.get("style", "")
+        if s == "bold":
+            sty["fontWeight"] = 700
+        elif s == "italic":
+            sty["fontStyle"] = "italic"
+        elif s == "bold-italic":
+            sty.update({"fontWeight": 700, "fontStyle": "italic"})
+
+        # 主題雙色（light / dark）
+        cls = None
+        if r.get("color_light") or r.get("color_dark"):
+            if r.get("color_light"):
+                sty["--tc-light"] = r["color_light"]
+            if r.get("color_dark"):
+                sty["--tc-dark"] = r["color_dark"]
+            sty["color"] = "var(--tc, var(--tc-light))"
+            cls = "themed-color"
+
+        out.append(html.Span(r.get("text", ""), style=sty, className=cls))
+
+    return out

firebase_init.py

@@ -0,0 +1,46 @@
+"""
+firebase_init.py
+----------------
+Firebase Admin SDK 初始化（單例模式）。
+放在專案根目錄，其他模組 import 即可。
+"""
+from __future__ import annotations
+import os, json
+from pathlib import Path
+
+_db = None  # 全域單例
+
+def get_db():
+    """取得 Firestore client（延遲初始化）。"""
+    global _db
+    if _db is not None:
+        return _db
+
+    try:
+        import firebase_admin
+        from firebase_admin import credentials, firestore
+    except ImportError:
+        raise RuntimeError(
+            "請先安裝 firebase-admin：pip install firebase-admin --break-system-packages"
+        )
+
+    if firebase_admin._apps:
+        _db = firestore.client()
+        return _db
+
+    # 優先讀取 firebase_key.json（本機開發）
+    key_file = Path(__file__).resolve().parent / "firebase_key.json"
+    if key_file.exists():
+        cred = credentials.Certificate(str(key_file))
+    else:
+        # 從環境變數讀取（Hugging Face Secrets）
+        sa_json = os.getenv("FIREBASE_SERVICE_ACCOUNT")
+        if not sa_json:
+            raise RuntimeError(
+                "找不到 Firebase 憑證。請放置 firebase_key.json 或設定環境變數 FIREBASE_SERVICE_ACCOUNT。"
+            )
+        cred = credentials.Certificate(json.loads(sa_json))
+
+    firebase_admin.initialize_app(cred)
+    _db = firestore.client()
+    return _db

firebase_progress.py

@@ -0,0 +1,127 @@
+"""
+firebase_progress.py
+--------------------
+學生學習進度的讀寫邏輯。
+放在專案根目錄，由 dt_callbacks.py 和頁面呼叫。
+
+Firestore 資料結構：
+  students/{student_id}/
+    profile:  { name, student_id, last_seen }
+    progress: { quiz_correct, solutions_viewed, ai_hints_used, ... }
+    events:   [ { type, unit, qid, ts, ... }, ... ]  ← 子集合
+"""
+from __future__ import annotations
+import datetime
+from firebase_init import get_db
+
+# ─── 時間戳 ────────────────────────────────────────────────────────────────
+def _now() -> str:
+    return datetime.datetime.now(datetime.timezone.utc).isoformat()
+
+
+# ─── 學生個人資料 ──────────────────────────────────────────────────────────
+
+def upsert_student(student_id: str, name: str = "") -> None:
+    """建立或更新學生個人資料。"""
+    db = get_db()
+    ref = db.collection("students").document(student_id)
+    ref.set({
+        "student_id": student_id,
+        "name": name or student_id,
+        "last_seen": _now(),
+    }, merge=True)
+
+
+# ─── 記錄事件 ─────────────────────────────────────────────────────────────
+
+def log_event(student_id: str, event_type: str, **kwargs) -> None:
+    """
+    記錄一筆學習事件到 students/{student_id}/events 子集合。
+
+    event_type 範例：
+        "quiz_correct"    - 填空/選擇題答對
+        "quiz_wrong"      - 答錯
+        "solution_viewed" - 展開詳細解法
+        "hint_used"       - 按下 AI 提示
+        "quiz_ai_done"    - AI 批改完成
+    """
+    db = get_db()
+    payload = {
+        "type": event_type,
+        "ts": _now(),
+        **kwargs,  # unit, qid, answer, ...
+    }
+    db.collection("students").document(student_id)\
+      .collection("events").add(payload)
+
+
+def log_quiz_result(
+    student_id: str,
+    unit: str,
+    qid: str,
+    correct: bool,
+    answer: str = "",
+) -> None:
+    """記錄一題答題結果，同時更新 progress 計數。"""
+    event_type = "quiz_correct" if correct else "quiz_wrong"
+    log_event(student_id, event_type, unit=unit, qid=qid, answer=answer)
+
+    # 更新統計計數
+    db = get_db()
+    ref = db.collection("students").document(student_id)
+    field = "quiz_correct_count" if correct else "quiz_wrong_count"
+    ref.set({field: _increment(1), "last_seen": _now()}, merge=True)
+
+
+def log_solution_viewed(student_id: str, unit: str, solution_id: str) -> None:
+    """記錄學生展開了某個解法區塊。"""
+    log_event(student_id, "solution_viewed", unit=unit, solution_id=solution_id)
+    db = get_db()
+    db.collection("students").document(student_id)\
+      .set({"solutions_viewed_count": _increment(1), "last_seen": _now()}, merge=True)
+
+
+def log_hint_used(student_id: str, unit: str, qid: str) -> None:
+    """記錄學生使用了 AI 提示。"""
+    log_event(student_id, "hint_used", unit=unit, qid=qid)
+    db = get_db()
+    db.collection("students").document(student_id)\
+      .set({"ai_hints_used_count": _increment(1), "last_seen": _now()}, merge=True)
+
+
+# ─── 讀取 ────────────────────────────────────────────────────────────────
+
+def get_student_progress(student_id: str) -> dict:
+    """讀取單一學生的 progress 計數（老師後台用）。"""
+    db = get_db()
+    doc = db.collection("students").document(student_id).get()
+    if doc.exists:
+        return doc.to_dict()
+    return {}
+
+
+def get_all_students() -> list[dict]:
+    """讀取所有學生的 profile（老師後台列表用）。"""
+    db = get_db()
+    docs = db.collection("students").stream()
+    return [d.to_dict() for d in docs]
+
+
+def get_student_events(student_id: str, limit: int = 100) -> list[dict]:
+    """讀取某學生最近的事件記錄。"""
+    db = get_db()
+    docs = (
+        db.collection("students").document(student_id)
+          .collection("events")
+          .order_by("ts", direction="DESCENDING")
+          .limit(limit)
+          .stream()
+    )
+    return [d.to_dict() for d in docs]
+
+
+# ─── Firestore 遞增輔助 ───────────────────────────────────────────────────
+
+def _increment(n: int):
+    from google.cloud.firestore import Increment
+    return Increment(n)

firebase_quiz_hooks.py

@@ -0,0 +1,75 @@
+"""
+firebase_quiz_hooks.py
+----------------------
+答題記錄已移至 dt_callbacks.py 直接處理。
+這裡只保留解法展開和 AI 提示的記錄。
+"""
+from __future__ import annotations
+from dash import callback, Input, Output, State, ALL, no_update, ctx, dcc
+
+
+def create_dummy_stores():
+    return [dcc.Store(id="_fq-log", data={})]
+
+
+@callback(
+    Output("_fq-log", "data"),
+    Input({"type": "solution-toggle", "key": ALL}, "n_clicks"),
+    State({"type": "solution-toggle", "key": ALL}, "id"),
+    State("student-id-store", "data"),
+    State("page-url", "pathname"),
+    prevent_initial_call=True,
+)
+def record_solution(n_clicks_list, ids, student_id, pathname):
+    if not student_id:
+        return no_update
+    trigger = ctx.triggered_id
+    if not trigger or not isinstance(trigger, dict):
+        return no_update
+    key = trigger.get("key", "")
+    unit = (pathname or "").strip("/").replace("/", "_") or "unknown"
+    for i, pid in enumerate(ids):
+        if isinstance(pid, dict) and pid.get("key") == key:
+            if (n_clicks_list[i] or 0) == 1:
+                try:
+                    from firebase_progress import log_solution_viewed
+                    log_solution_viewed(student_id, unit, key)
+                except Exception as e:
+                    print(f"[Firebase] log_solution_viewed 失敗：{e}")
+            break
+    return no_update
+
+
+@callback(
+    Output("_fq-log", "data", allow_duplicate=True),
+    Input({"type": "quiz-hint",        "qid": ALL}, "n_clicks"),
+    Input({"type": "quiz-hint-choice", "qid": ALL}, "n_clicks"),
+    State({"type": "quiz-hint",        "qid": ALL}, "id"),
+    State({"type": "quiz-hint-choice", "qid": ALL}, "id"),
+    State("student-id-store", "data"),
+    State("page-url", "pathname"),
+    prevent_initial_call=True,
+)
+def record_hint(fill_clicks, choice_clicks, fill_ids, choice_ids, student_id, pathname):
+    if not student_id:
+        return no_update
+    trigger = ctx.triggered_id
+    if not trigger or not isinstance(trigger, dict):
+        return no_update
+    qid   = trigger.get("qid", "")
+    qtype = trigger.get("type", "")
+    if not qid or "hint" not in qtype:
+        return no_update
+    unit   = (pathname or "").strip("/").replace("/", "_") or "unknown"
+    ids    = fill_ids    if qtype == "quiz-hint" else choice_ids
+    clicks = fill_clicks if qtype == "quiz-hint" else choice_clicks
+    for i, pid in enumerate(ids):
+        if isinstance(pid, dict) and pid.get("qid") == qid:
+            if (clicks[i] or 0) == 1:
+                try:
+                    from firebase_progress import log_hint_used
+                    log_hint_used(student_id, unit, qid)
+                except Exception as e:
+                    print(f"[Firebase] log_hint_used 失敗：{e}")
+            break
+    return no_update

ggb.py

@@ -0,0 +1,160 @@
+import dash
+from dash import dcc, html, Input, Output
+import plotly.graph_objects as go
+import numpy as np
+
+# --- 1. ?????? ---
+def f(x, y):
+    return 4 - x**2 - 2*y**2
+
+def df_dx(x, y): # ? x ??
+    return -2 * x
+
+def df_dy(x, y): # ? y ??
+    return -4 * y
+
+# --- 2. ??? Dash App ---
+app = dash.Dash(__name__)
+
+# --- 3. ???? (Layout) ---
+app.layout = html.Div([
+    html.H2("????????? (Python?)", style={'textAlign': 'center'}),
+    
+    # ????
+    html.Div([
+        html.Div([
+            html.Label("?? a ?:"),
+            dcc.Input(id='input-a', type='number', value=1, step=0.1),
+        ], style={'marginRight': '20px', 'display': 'inline-block'}),
+        
+        html.Div([
+            html.Label("?? b ?:"),
+            dcc.Input(id='input-b', type='number', value=1, step=0.1),
+        ], style={'marginRight': '20px', 'display': 'inline-block'}),
+        
+        # ?? Checklist ??????
+        dcc.Checklist(
+            id='toggle-switches',
+            options=[
+                {'label': ' ???? C1 (x??)', 'value': 'show_c1'},
+                {'label': ' ???? T1', 'value': 'show_t1'},
+                {'label': ' ???? C2 (y??)', 'value': 'show_c2'},
+                {'label': ' ???? T2', 'value': 'show_t2'},
+            ],
+            value=[], # ?????
+            inline=True
+        )
+    ], style={'padding': '20px', 'backgroundColor': '#f9f9f9'}),
+
+    # ??????
+    html.Div(id='slope-info', style={'padding': '10px', 'fontSize': '18px', 'fontWeight': 'bold'}),
+
+    # 3D ???
+    dcc.Graph(id='3d-surface-plot', style={'height': '80vh'})
+])
+
+# --- 4. ???? (??????) ---
+@app.callback(
+    [Output('3d-surface-plot', 'figure'),
+     Output('slope-info', 'children')],
+    [Input('input-a', 'value'),
+     Input('input-b', 'value'),
+     Input('toggle-switches', 'value')]
+)
+def update_graph(a, b, toggles):
+    # ??????????????????
+    if a is None: a = 1
+    if b is None: b = 1
+    
+    # ?? P ???
+    z_val = f(a, b)
+    
+    # --- ?????? ---
+    x_range = np.linspace(-3, 3, 50)
+    y_range = np.linspace(-3, 3, 50)
+    X, Y = np.meshgrid(x_range, y_range)
+    Z = f(X, Y)
+    
+    fig = go.Figure()
+    
+    # 1. ??? (???)
+    fig.add_trace(go.Surface(z=Z, x=X, y=Y, colorscale='Viridis', opacity=0.6, showscale=False, name='??'))
+    
+    # 2. ? P ?
+    fig.add_trace(go.Scatter3d(
+        x=[a], y=[b], z=[z_val],
+        mode='markers', marker=dict(size=6, color='black'),
+        name=f'P({a},{b})'
+    ))
+
+    # --- ?? C1 ? T1 (? x ??) ---
+    slope_x = df_dx(a, b)
+    info_text = []
+
+    if 'show_c1' in toggles:
+        # C1: ?? y=b, x ??
+        t = np.linspace(-3, 3, 50)
+        fig.add_trace(go.Scatter3d(
+            x=t, y=[b]*50, z=f(t, b),
+            mode='lines', line=dict(color='red', width=5),
+            name='C1 (?? y=b)'
+        ))
+    
+    if 'show_t1' in toggles:
+        # T1: ?? (?????????)
+        # ????? (1, 0, slope_x)
+        t_tan = np.linspace(-1.5, 1.5, 10) # ????
+        x_tan = a + t_tan
+        y_tan = [b] * 10
+        z_tan = z_val + slope_x * t_tan
+        
+        fig.add_trace(go.Scatter3d(
+            x=x_tan, y=y_tan, z=z_tan,
+            mode='lines', line=dict(color='red', width=4, dash='dash'),
+            name=f'T1 ?? (m={slope_x:.2f})'
+        ))
+        info_text.append(f"x???? (fx) = {slope_x:.2f}")
+
+    # --- ?? C2 ? T2 (? y ??) ---
+    slope_y = df_dy(a, b)
+    
+    if 'show_c2' in toggles:
+        # C2: ?? x=a, y ??
+        t = np.linspace(-3, 3, 50)
+        fig.add_trace(go.Scatter3d(
+            x=[a]*50, y=t, z=f(a, t),
+            mode='lines', line=dict(color='blue', width=5),
+            name='C2 (?? x=a)'
+        ))
+
+    if 'show_t2' in toggles:
+        # T2 ??
+        # ????? (0, 1, slope_y)
+        t_tan = np.linspace(-1.5, 1.5, 10)
+        x_tan = [a] * 10
+        y_tan = b + t_tan
+        z_tan = z_val + slope_y * t_tan
+        
+        fig.add_trace(go.Scatter3d(
+            x=x_tan, y=y_tan, z=z_tan,
+            mode='lines', line=dict(color='blue', width=4, dash='dash'),
+            name=f'T2 ?? (m={slope_y:.2f})'
+        ))
+        info_text.append(f"y???? (fy) = {slope_y:.2f}")
+
+    # --- ????????? ---
+    fig.update_layout(
+        scene=dict(
+            xaxis=dict(range=[-3, 3]),
+            yaxis=dict(range=[-3, 3]),
+            zaxis=dict(range=[-5, 5]),
+            aspectratio=dict(x=1, y=1, z=0.7)
+        ),
+        margin=dict(l=0, r=0, b=0, t=0)
+    )
+
+    return fig, " | ".join(info_text) if info_text else "????????????"
+
+# --- 5. ????? ---
+if __name__ == '__main__':
+    app.run(debug=True)

layout/Chapter_card.py

@@ -0,0 +1,56 @@
+"""
+layout/Chapter_card.py  ← 向下相容 shim
+----------------------------------------
+create_card 已整合進 layout/renderer/ 的 cards 模組。
+此 shim 讓舊 import 繼續正常運作：
+
+    from layout.Chapter_card import create_card   ← 仍可用
+"""
+from .renderer.renderer import render_doc as _  # 確保 renderer 已初始化  # noqa: F401
+
+# Chapter_card 的原始功能直接在此定義（避免 components/ 路徑問題）
+from dash import html
+import dash_mantine_components as dmc
+from dash_iconify import DashIconify
+
+
+def create_card(data: dict) -> dmc.Card:
+    """章節總覽卡片（原 Chapter_card.py）。"""
+    buttons = [
+        dmc.Anchor(
+            href=data["link"],
+            children=dmc.Button("單元學習", variant="light", color="orange", size="sm", radius="xl"),
+        )
+    ]
+    if "trick" in data:
+        buttons.append(
+            dmc.Anchor(
+                href=data["trick"],
+                children=dmc.Button("技巧學習", variant="outline", color="gray", size="sm", radius="xl"),
+            )
+        )
+    buttons.append(
+        dmc.Anchor(
+            href=data["test"],
+            children=dmc.Button("小測驗", variant="filled", color="blue", size="sm", radius="xl"),
+        )
+    )
+    desc_items = [dmc.Text(line, size="sm", c="dimmed") for line in data["description"]]
+    desc_items += [dmc.Text(" ", size="sm") for _ in range(4 - len(data["description"]))]
+
+    return dmc.Card(
+        children=[
+            dmc.Text(data["title"], fw=700, size="lg"),
+            dmc.Group(
+                gap="xs", mt="xs", mb="sm",
+                children=[dmc.Badge(label, color=color, radius="md") for label, color in data["badges"]],
+            ),
+            dmc.Stack(gap=0, style={"minHeight": 100}, children=desc_items),
+            dmc.Flex(gap="sm", wrap="wrap", justify="flex-start", mt="sm", children=buttons),
+        ],
+        withBorder=True, shadow="sm", radius="md",
+        style={"width": {"base": 280, "sm": 320, "md": 350, "lg": 400}},
+    )
+
+
+__all__ = ["create_card"]

layout/__init__.py

@@ -0,0 +1,25 @@
+"""
+layout/__init__.py
+------------------
+統一 re-export 各子資料夾的常用 API，
+讓 pages/ 裡的 import 路徑保持簡短。
+"""
+
+# Shell 元件
+from .shell.header    import generate_header              # noqa: F401
+from .shell.navbar    import generate_navbar              # noqa: F401
+from .shell.main      import generate_main                # noqa: F401
+from .shell.footer    import generate_footer              # noqa: F401
+from .shell.callbacks import generate_toggle_navbar, switch_light_dark  # noqa: F401
+
+# 轉換器
+from .converter.md_pipeline import build_from_config        # noqa: F401
+
+# 渲染引擎
+from .renderer.renderer import (                          # noqa: F401
+    render_doc,
+    install_callbacks_once,
+)
+
+# 頁面組裝
+from .page.page_layout import make_test_page              # noqa: F401

layout/converter/__init__.py

@@ -0,0 +1,8 @@
+"""
+converter/ — Markdown → JSON 轉換器
+外部可直接用：from layout.converter import build_from_config
+"""
+from .md_io import build_from_config  # noqa: F401
+
+# 進階用途（頁面直接解析 MD）
+from .md_blocks import parse_document  # noqa: F401

layout/converter/md_attrs.py

@@ -0,0 +1,82 @@
+"""
+md_attrs.py
+-----------
+HTML 註解屬性字串解析。
+
+公開 API：
+    _attrs_to_dict(s)   → dict   （通用版，支援帶連字號的 key）
+    _parse_attrs(s)     → dict   （quiz block 變體，支援 bare flag）
+    _slug_ascii(t)      → str    （ASCII 化 slug，供 quiz id 使用）
+"""
+from __future__ import annotations
+import re
+import hashlib
+import unicodedata
+
+# ---------------------------------------------------------------------------
+# 正規表達式
+# ---------------------------------------------------------------------------
+
+# 通用版：支援帶連字號的 key，例如 hint_a="..."
+_Q_ATTR = re.compile(
+    r'([A-Za-z_][A-Za-z0-9_-]*)\s*=\s*"([^"]*)"'
+    r'|([A-Za-z_][A-Za-z0-9_-]*)\s*=\s*([^\s">]+)'
+)
+
+# quiz block 變體（_parse_attrs 用）：額外支援 bare flag（沒有值的 key）
+_QUIZ_ATTR = re.compile(
+    r'([A-Za-z_][\w-]*)\s*=\s*"([^"]*)"|([A-Za-z_][\w-]*)\s*=\s*([^\s">]+)|([A-Za-z_][\w-]*)'
+)
+
+# ---------------------------------------------------------------------------
+# 公開函式
+# ---------------------------------------------------------------------------
+
+def _attrs_to_dict(s: str) -> dict[str, str]:
+    """
+    把 HTML 註解屬性字串解析為 dict。
+
+    支援：
+        key="value"   →  {key: value}
+        key=value     →  {key: value}
+    """
+    out: dict[str, str] = {}
+    if not s:
+        return out
+    for m in _Q_ATTR.finditer(s):
+        if m.group(1) and m.group(2) is not None:
+            out[m.group(1)] = m.group(2)
+        elif m.group(3) and m.group(4) is not None:
+            out[m.group(3)] = m.group(4)
+    return out
+
+
+def _parse_attrs(s: str) -> dict[str, str]:
+    """
+    quiz block 屬性解析變體，額外支援 bare flag（key 無值時設為 "1"）。
+    """
+    out: dict[str, str] = {}
+    for m in _QUIZ_ATTR.finditer(s or ""):
+        if m.group(1):
+            out[m.group(1)] = m.group(2)
+        elif m.group(3):
+            out[m.group(3)] = m.group(4)
+        elif m.group(5):
+            out[m.group(5)] = "1"
+    return out
+
+
+def _slug_ascii(t: str, prefix: str = "order") -> str:
+    """
+    把任意字串轉成 ASCII slug（供 quiz id 使用）。
+    無法轉換時用 sha1 hash 作為 fallback。
+    """
+    t_norm = unicodedata.normalize("NFKD", t)
+    t_ascii = "".join(
+        ch for ch in t_norm if ch.isascii() and (ch.isalnum() or ch in "-_ ")
+    )
+    t_ascii = "-".join(t_ascii.strip().lower().split())
+    if t_ascii:
+        return t_ascii
+    h = hashlib.sha1(t.encode("utf-8")).hexdigest()[:8]
+    return f"{prefix}-{h}"

layout/converter/md_blocks.py

@@ -0,0 +1,970 @@
+"""
+md_blocks.py
+------------
+段落 / 清單 / 特殊區塊（card、quiz、flow、solution、ggb、icon）解析，
+以及文件級 parse_document 與 TOC 指派。
+
+依賴：md_color, md_tex, md_attrs, md_runs
+
+公開 API：
+    parse_document(text)              → List[block]   主要入口
+    parse_content_block(text)         → List[block]
+    parse_solution_block(src)         → block
+    parse_card_block(src)             → block
+    parse_interactive_block(src)      → block
+    parse_flow_block(src)             → block
+    parse_quizzes(md)                 → List[block]
+    parse_geogebra_marker(s)          → block
+    parse_icon_marker(s)              → block
+    parse_pyfunc_marker(s)            → block
+    parse_list_items(list_block)      → List[item]
+    parse_paragraph_runs_color_aware  → List[run]
+    parse_line_color_aware            → List[run]
+    assign_ids_and_build_toc(nodes)   → List[toc_entry]
+    split_blocks_into_sections(blocks)→ List[section]
+    build_ai_prompt_for_example(...)  → str
+    build_ai_prompt_for_pos(...)      → str
+    build_ai_prompt_for_solution_pos(...)→ str
+"""
+from __future__ import annotations
+import re
+import hashlib
+import unicodedata
+import json
+
+from .md_color import attach_theme_colors, _norm_hex
+from .md_tex   import _ensure_inline_dollars, _ensure_block_dollars
+from .md_attrs import _attrs_to_dict, _parse_attrs, _slug_ascii
+from .md_runs  import (
+    build_inline_runs, normalize_runs,
+    _has_newline_token, _plain_text_from_runs,
+    _append_hard_break,
+    _split_text_and_any_display_math,
+    _split_text_links_images, _split_text_and_ggb, _split_text_and_icon,
+)
+
+# ---------------------------------------------------------------------------
+# 模組級正規表達式（只保留 md_blocks 內部用的）
+# ---------------------------------------------------------------------------
+_COLOR_TAG     = re.compile(r'<!--c_([A-Za-z0-9#]+)-->|\s*<!--c_([A-Za-z0-9#]+)_end-->')
+_SOL_OPEN      = re.compile(r'<!--\s*solution(?P<attrs>[^>]*)-->', re.IGNORECASE)
+_SOL_CLOSE     = re.compile(r'<!--\s*solution_end\s*-->', re.IGNORECASE)
+_SOL_END_RE    = re.compile(r'<!--\s*solution_end\s*-->', re.IGNORECASE)
+_EXAMPLE_RE    = re.compile(r'^\s*###\s*Example[^\n]*', re.MULTILINE)
+_PROBLEM_RE    = re.compile(r'<!--\s*problem\s*-->', re.IGNORECASE)
+_SOLUTION_OPEN_RE = re.compile(r'<!--\s*solution\s*-->')
+_TAG_ONLY_RE   = re.compile(r'^<!--\s*([A-Za-z0-9_-]+)\s*-->$')
+_SPLIT_AFTER_COLOR_CLOSE_TO_NEW_ITEM = re.compile(
+    r'^(?P<left>.*?<!--c_[A-Za-z0-9#]+_end-->)(?:\s*)(?P<right>(?P<indent>\s*)(?P<marker>\d+\.)\s+.*)$'
+)
+_BLANKPARA_SPLIT = re.compile(r'(\n\s*\n+)')
+_PYFUNC_RE     = re.compile(r'<!--\s*pyfunc(?P<attrs>[^>]*)-->')
+_GGB_SINGLE_RE = re.compile(r'^\s*<!--\s*ggb(?P<attrs>[^>]*)-->\s*$', re.S)
+_ICON_SINGLE_RE = re.compile(r'^\s*<!--\s*icon(?P<attrs>[^>]*)-->\s*$', re.S | re.I)
+_CARD_RE       = re.compile(r'<!--\s*card(?P<attrs>[^>]*)-->(?P<body>.*?)<!--\s*card_end\s*-->', re.S)
+_FLOW_RE       = re.compile(r'<!--\s*flow(?P<attrs>[^>]*)-->(?P<body>.*?)<!--\s*flow_end\s*-->', re.S)
+_STEP_RE       = re.compile(r'<!--\s*step(?P<attrs>[^>]*)-->(?P<body>.*?)<!--\s*step_end\s*-->', re.S)
+QUIZ_OPEN      = re.compile(r'<!--\s*quiz\s+(?P<attrs>[^>]*)-->')
+QUIZ_END       = re.compile(r'<!--\s*quiz_end\s*-->')
+STEP_RE_SIMPLE = re.compile(r'<!--step-->\s*(.*)')
+_FILE_MARKER_RE = re.compile(r'<!--\s*file(?:_|[\s]+)(?P<path>[^>\r\n]+?)\s*-->', re.IGNORECASE)
+
+# 全域原始 MD（供 AI prompt 查詢用，由 md_io._export_one 注入）
+_ROOT_MD: str = ""
+
+# flow id 計數器
+_FLOW_SEQ: int = 0
+
+# ---------------------------------------------------------------------------
+# AI Prompt 輔助
+# ---------------------------------------------------------------------------
+
+def build_ai_prompt_for_example(full_md: str, example_seq: int) -> str:
+    """回傳第 example_seq 個 Example 標題到第一個 <!--solution--> 之前的文字。"""
+    if not full_md or example_seq <= 0:
+        return ""
+    ex_iter = list(_EXAMPLE_RE.finditer(full_md))
+    if example_seq > len(ex_iter):
+        return ""
+    ex_m  = ex_iter[example_seq - 1]
+    sol_m = _SOLUTION_OPEN_RE.search(full_md, pos=ex_m.start())
+    end   = sol_m.start() if sol_m else len(full_md)
+    return full_md[ex_m.start():end].strip()
+
+
+def build_ai_prompt_for_solution_pos(full_md: str, pos: int) -> str:
+    """solution block 的 AI prompt：從最近的 Example 到 pos，若中間有 solution_end 則回空。"""
+    if not full_md or pos is None or pos < 0:
+        return ""
+    search_region = full_md[:pos]
+    last_example  = None
+    for m in _EXAMPLE_RE.finditer(search_region):
+        last_example = m
+    if not last_example:
+        return ""
+    seg = search_region[last_example.end():]
+    if _SOL_END_RE.search(seg):
+        return ""
+    return full_md[last_example.start():pos].strip()
+
+
+def build_ai_prompt_for_pos(full_md: str, pos: int) -> str:
+    """給定 pos，往上��最近的 ### Example 或 <!--problem-->，抽出 prompt 文字。"""
+    if not full_md or pos is None or pos < 0:
+        return ""
+    search_region = full_md[:pos]
+    last_example  = None
+    for m in _EXAMPLE_RE.finditer(search_region):
+        last_example = m
+    last_problem = None
+    for m in _PROBLEM_RE.finditer(search_region):
+        last_problem = m
+    if not last_example and not last_problem:
+        return ""
+    if last_example:
+        seg = search_region[last_example.end():]
+        if _SOL_END_RE.search(seg):
+            last_example = None
+    if not last_example and not last_problem:
+        return ""
+    if last_example and (not last_problem or last_example.start() > last_problem.start()):
+        start = last_example.start()
+    else:
+        start = last_problem.end()
+    return full_md[start:pos].strip()
+
+# ---------------------------------------------------------------------------
+# TOC / ID 相關
+# ---------------------------------------------------------------------------
+
+def _make_unique_id(base: str, used: set) -> str:
+    hid, i = base, 1
+    while hid in used:
+        i += 1
+        hid = f"{base}-{i}"
+    used.add(hid)
+    return hid
+
+
+def _slugify_heading(text: str) -> str:
+    t = unicodedata.normalize("NFKC", text)
+    t = re.sub(r'\s+', '-', t.strip())
+    t = re.sub(r'[^A-Za-z0-9\-_]+', '-', t)
+    t = re.sub(r'-{2,}', '-', t).strip('-')
+    return t or "sec"
+
+
+def assign_ids_and_build_toc(nodes: list[dict]) -> list[dict]:
+    """為 heading 節點指派 id，並回傳 TOC 清單。"""
+    current_tag, tag_counters, used_ids, toc = None, {}, set(), []
+    for n in nodes:
+        if n.get('type') == 'comment':
+            m = _TAG_ONLY_RE.match(n.get('content', '').strip())
+            if m:
+                current_tag = m.group(1)
+                tag_counters.setdefault(current_tag, 0)
+            continue
+        if n.get('type') == 'heading':
+            title = n.get('content', '').strip()
+            if current_tag:
+                tag_counters[current_tag] += 1
+                base = f"{current_tag}_id{tag_counters[current_tag]}"
+            else:
+                base = _slugify_heading(title)
+            hid = _make_unique_id(base, used_ids)
+            n['id'] = hid
+            toc.append({'label': title, 'id': hid, 'level': n.get('level', 2)})
+    return toc
+
+
+def split_blocks_into_sections(blocks: list[dict]) -> list[dict]:
+    """按 H2 heading 把 blocks 切成 sections，第一個為「全部」。"""
+    sections: list[dict] = [{"id": "sec-all", "title": "全部", "blocks": blocks[:]}]
+    current, sec_idx = None, 0
+    for b in blocks:
+        if b.get("type") == "heading" and int(b.get("level", 0)) == 2:
+            if current:
+                sections.append(current)
+            sec_idx += 1
+            current = {
+                "id": f"sec-{sec_idx}",
+                "title": (b.get("content") or f"段落 {sec_idx}").strip(),
+                "blocks": [b],
+            }
+        else:
+            if current is not None:
+                current["blocks"].append(b)
+    if current:
+        sections.append(current)
+    return sections
+
+# ---------------------------------------------------------------------------
+# 段落 / 清單解析
+# ---------------------------------------------------------------------------
+
+def _split_midline_new_item(line: str) -> tuple[str | None, str | None]:
+    m = _SPLIT_AFTER_COLOR_CLOSE_TO_NEW_ITEM.match(line)
+    if not m:
+        return None, None
+    return m.group('left'), m.group('right')
+
+
+def _emit_blank_paragraph(parsed_content: list) -> None:
+    parsed_content.append({'type': 'paragraph', 'content': '', 'runs': [], 'newline': 'true'})
+
+
+def _append_blankline_runs(blank_token: str, out_runs: list) -> None:
+    n = max(1, blank_token.count('\n') - 1)
+    for _ in range(n):
+        out_runs.append({'text': '', 'newline': 'true', '_blank': '1'})
+
+
+def parse_line_color_aware(line: str, color_stack: list) -> list[dict]:
+    """把一行切成 runs，依 color_stack 上色，處理 <!--c_xxx--> 標記。"""
+    pos, out = 0, []
+
+    def cur_color():
+        return color_stack[-1] if color_stack else None
+
+    for m in _COLOR_TAG.finditer(line):
+        chunk = line[pos:m.start()]
+        if chunk:
+            for tk in _split_text_and_any_display_math(chunk):
+                if tk.get("kind") == "math_block":
+                    run = {'latex': tk["latex"], 'kind': 'math_block'}
+                    if cur_color():
+                        run['color'] = cur_color()
+                        attach_theme_colors(run)
+                    out.append(run)
+                else:
+                    runs = build_inline_runs(tk["text"] or "")
+                    if cur_color():
+                        for r in runs:
+                            r.setdefault('color', cur_color())
+                            attach_theme_colors(r)
+                    out.extend(runs)
+        if m.group(1):
+            color_stack.append(m.group(1))
+        else:
+            name = m.group(2)
+            for k in range(len(color_stack) - 1, -1, -1):
+                if color_stack[k] == name:
+                    color_stack.pop(k); break
+        pos = m.end()
+
+    tail = line[pos:]
+    if tail:
+        for tk in _split_text_and_any_display_math(tail):
+            if tk.get("kind") == "math_block":
+                run = {'latex': tk["latex"], 'kind': 'math_block'}
+                if cur_color():
+                    run['color'] = cur_color()
+                    attach_theme_colors(run)
+                out.append(run)
+            else:
+                runs = build_inline_runs(tk["text"] or "")
+                if cur_color():
+                    for r in runs:
+                        r.setdefault('color', cur_color())
+                        attach_theme_colors(r)
+                out.extend(runs)
+    return out
+
+
+def parse_paragraph_runs_color_aware(block_text: str) -> list[dict]:
+    """多行段落 → runs（含 $$ block math、硬換行）。"""
+    lines = (block_text or "").splitlines(keepends=True)
+    i, color_stack, runs = 0, [], []
+    PARA_DOLLAR_LINE = re.compile(r'^\s*\$\$(.*)$')
+
+    while i < len(lines):
+        ln = lines[i]
+        m_dollar = PARA_DOLLAR_LINE.match(ln.rstrip('\r\n'))
+        if m_dollar:
+            latex_lines, first = [], m_dollar.group(1)
+            if re.search(r'\$\$\s*$', first):
+                latex_lines.append(re.sub(r'\$\$\s*$', '', first))
+            else:
+                i += 1
+                while i < len(lines):
+                    seg = lines[i].rstrip('\r\n')
+                    if re.search(r'\$\$\s*$', seg):
+                        latex_lines.append(re.sub(r'\$\$\s*$', '', seg)); break
+                    latex_lines.append(seg); i += 1
+            latex = "\n".join(latex_lines).strip()
+            run = {'latex': _ensure_block_dollars(latex), 'kind': 'math_block'}
+            if color_stack:
+                run['color'] = color_stack[-1]
+                attach_theme_colors(run)
+            runs.append(run); i += 1; continue
+
+        raw = ln
+        if re.search(r'[ ]{2,}\r?\n$', raw):
+            body = re.sub(r'[ ]{2,}\r?\n$', '', raw)
+            runs.extend(parse_line_color_aware(body, color_stack))
+            _append_hard_break(runs)
+        else:
+            runs.extend(parse_line_color_aware(raw.rstrip('\r\n'), color_stack))
+        i += 1
+
+    return normalize_runs(runs)
+
+
+def parse_list_items(list_block: str) -> list[dict]:
+    """解析清單 block，回傳帶 indent / marker / runs / content 的 item 清單。"""
+    lines, i = list_block.splitlines(), 0
+    list_items, color_stack = [], []
+    INDENT_PER_LEVEL = 2
+    item_re = re.compile(r'^(?P<indent>\s*)(?P<marker>[*+\-]|\d+\.)\s+(?P<content>.*)$')
+
+    def _parse_dollar_block(start_i):
+        """從 lines[start_i] 開始讀 $$...$$ block，回傳 (latex_str, next_i)。"""
+        m_d = re.match(r'^\s*\$\$(.*)$', lines[start_i])
+        if not m_d:
+            return None, start_i
+        latex_lines, first = [], m_d.group(1)
+        if re.search(r'\$\$\s*$', first):
+            latex_lines.append(re.sub(r'\$\$\s*$', '', first))
+            return "\n".join(latex_lines).strip(), start_i + 1
+        j = start_i + 1
+        while j < len(lines):
+            seg = lines[j]
+            if re.search(r'\$\$\s*$', seg):
+                latex_lines.append(re.sub(r'\$\$\s*$', '', seg)); j += 1; break
+            latex_lines.append(seg); j += 1
+        return "\n".join(latex_lines).strip(), j
+
+    while i < len(lines):
+        line = lines[i]
+        m = item_re.match(line)
+
+        if not m:
+            if list_items and line.strip():
+                left, right = _split_midline_new_item(line)
+                if right:
+                    list_items[-1]['runs'].extend(parse_line_color_aware((left or '').strip(), color_stack))
+                    list_items[-1]['content'] = _plain_text_from_runs(list_items[-1]['runs'])
+                    lines.insert(i + 1, right); i += 1; continue
+
+                latex, next_i = _parse_dollar_block(i)
+                if latex is not None:
+                    run = {'latex': _ensure_block_dollars(latex), 'kind': 'math_block'}
+                    if color_stack:
+                        run['color'] = color_stack[-1]; attach_theme_colors(run)
+                    list_items[-1]['runs'].append(run)
+                    list_items[-1]['content'] = _plain_text_from_runs(list_items[-1]['runs'])
+                    i = next_i; continue
+
+                list_items[-1]['runs'].extend(parse_line_color_aware(line.strip(), color_stack))
+                list_items[-1]['content'] = _plain_text_from_runs(list_items[-1]['runs'])
+            i += 1; continue
+
+        color_stack = []
+        raw_indent    = m.group('indent')
+        indent_spaces = raw_indent.expandtabs(INDENT_PER_LEVEL)
+        indent        = len(indent_spaces) // INDENT_PER_LEVEL
+        marker        = m.group('marker')
+        content       = m.group('content').rstrip()
+        runs          = parse_line_color_aware(content, color_stack)
+        list_items.append({'indent': indent, 'marker': marker, 'runs': runs, 'content': _plain_text_from_runs(runs)})
+        i += 1
+
+        while i < len(lines) and not item_re.match(lines[i]):
+            ln = lines[i]
+            if not ln.strip():
+                i += 1; continue
+            left, right = _split_midline_new_item(ln)
+            if right:
+                list_items[-1]['runs'].extend(parse_line_color_aware((left or '').strip(), color_stack))
+                list_items[-1]['content'] = _plain_text_from_runs(list_items[-1]['runs'])
+                lines.insert(i + 1, right); i += 1; continue
+            latex, next_i = _parse_dollar_block(i)
+            if latex is not None:
+                run = {'latex': _ensure_block_dollars(latex), 'kind': 'math_block'}
+                if color_stack:
+                    run['color'] = color_stack[-1]; attach_theme_colors(run)
+                list_items[-1]['runs'].append(run)
+                list_items[-1]['content'] = _plain_text_from_runs(list_items[-1]['runs'])
+                i = next_i; continue
+            list_items[-1]['runs'].extend(parse_line_color_aware(ln.strip(), color_stack))
+            list_items[-1]['content'] = _plain_text_from_runs(list_items[-1]['runs'])
+            i += 1
+
+    return list_items
+
+# ---------------------------------------------------------------------------
+# 特殊 marker 解析
+# ---------------------------------------------------------------------------
+
+def _ggb_id_from_url(u: str) -> str | None:
+    m = re.search(r'/m/([A-Za-z0-9]+)', u or '')
+    return m.group(1) if m else None
+
+
+def _ggb_node_from_attrs(attrs: dict) -> dict:
+    gid    = (attrs.get("id") or "").strip()
+    if not gid and "url" in attrs:
+        gid = _ggb_id_from_url(attrs.get("url", "")) or ""
+    return {
+        "type": "geogebra",
+        "id": gid,
+        "width":   attrs.get("w") or attrs.get("width")  or "100%",
+        "height":  attrs.get("h") or attrs.get("height") or "480",
+        "border":  attrs.get("border") or "0",
+        "caption": attrs.get("caption") or "",
+        "card":    attrs.get("card") or "0",
+    }
+
+
+def parse_geogebra_marker(s: str) -> dict:
+    m = _GGB_SINGLE_RE.search(s or '')
+    if not m:
+        return {"type": "paragraph", "content": s}
+    attrs = _attrs_to_dict(m.group('attrs') or "")
+    gid   = attrs.get("id") or _ggb_id_from_url(attrs.get("url", ""))
+    return {
+        "type": "geogebra",
+        "id": (gid or "").strip(),
+        "width":   attrs.get("w") or attrs.get("width")  or "100%",
+        "height":  attrs.get("h") or attrs.get("height") or "480",
+        "border":  attrs.get("border") or "0",
+        "caption": attrs.get("caption") or "",
+        "card":    attrs.get("card") or "0",
+    }
+
+
+def parse_icon_marker(s: str) -> dict:
+    """解析 <!--icon ...--> 為 icon 節點。"""
+    m = _ICON_SINGLE_RE.search(s or "")
+    if not m:
+        return {"type": "paragraph", "content": s}
+    attrs_str = (m.group("attrs") or "").strip()
+    attrs     = _attrs_to_dict(attrs_str)
+    icon      = (attrs.get("icon") or attrs.get("name") or "").strip()
+    height    = (attrs.get("height") or attrs.get("h") or "18").strip()
+    if not icon:
+        m2 = re.search(r'=\s*"([^"]+)"', attrs_str)
+        if m2:
+            icon = m2.group(1).strip()
+        elif attrs_str:
+            icon = attrs_str.strip()
+    return {"type": "icon", "icon": icon, "height": height}
+
+
+def parse_pyfunc_marker(s: str) -> dict:
+    m = _PYFUNC_RE.search(s or '')
+    if not m:
+        return {"type": "paragraph", "content": s}
+    attrs  = _attrs_to_dict(m.group('attrs') or "")
+    kwargs: dict = {}
+    if 'params' in attrs:
+        try:
+            kwargs = json.loads(attrs['params'])
+        except Exception:
+            kwargs = {}
+    for k, v in attrs.items():
+        if k not in ('path', 'call', 'params'):
+            kwargs.setdefault(k, v)
+    return {
+        "type":   "pyfunc",
+        "path":   (attrs.get("path") or "").strip(),
+        "call":   (attrs.get("call") or "make_view").strip(),
+        "kwargs": kwargs,
+    }
+
+
+def _parse_color_pair(token: str) -> tuple[str, str]:
+    s = (token or "").strip()
+    if not s:
+        return "", ""
+    if "|" in s:
+        a, b = s.split("|", 1)
+        return _norm_hex(a.strip()), _norm_hex(b.strip())
+    c = _norm_hex(s)
+    return c, c
+
+
+def parse_card_block(src: str) -> dict:
+    m = _CARD_RE.search(src)
+    if not m:
+        return {"type": "card", "content": src}
+    attrs = _attrs_to_dict(m.group("attrs") or "")
+    inner = (m.group("body") or "").strip()
+    kind     = attrs.get("type") or attrs.get("kind") or ""
+    headline = attrs.get("headline") or attrs.get("title") or ""
+
+    if not (kind and headline):
+        lines = inner.splitlines()
+        nz = [i for i, ln in enumerate(lines) if ln.strip()]
+        if nz:
+            if not kind:
+                kind = lines[nz[0]].strip(); lines[nz[0]] = ""
+            if len(nz) >= 2 and not headline:
+                headline = lines[nz[1]].strip(); lines[nz[1]] = ""
+            inner = "\n".join(lines).lstrip()
+
+    bg_l, bg_d = _parse_color_pair(attrs.get("bg") or attrs.get("background") or attrs.get("body_bg") or "")
+    fg_l, fg_d = _parse_color_pair(attrs.get("fg") or attrs.get("text") or attrs.get("header_fg") or "")
+    accent     = (attrs.get("accent") or attrs.get("badge") or attrs.get("palette") or "").strip()
+    body_blocks = parse_content_block(inner)
+    node = {"type": "card", "kind": kind, "headline": headline, "body": body_blocks}
+    if bg_l or bg_d: node["bg_light"], node["bg_dark"] = bg_l, bg_d
+    if fg_l or fg_d: node["fg_light"], node["fg_dark"] = fg_l, fg_d
+    if accent:       node["accent"] = accent
+    return node
+
+
+def _split_mcq_answers(ans_raw: str) -> list[str]:
+    raw = (ans_raw or "").strip().lower()
+    if not raw:
+        return []
+    raw = raw.replace("，", ",").replace("、", ",").replace(";", ",").replace("|", ",").replace(" ", ",")
+    raw = raw.strip(",")
+    if not raw:
+        return []
+    if re.fullmatch(r"[abcd]+", raw) and "," not in raw:
+        tokens = list(raw)
+    else:
+        tokens = [t for t in re.split(r"[,\s]+", raw) if t]
+    idxmap = {"1": "a", "2": "b", "3": "c", "4": "d"}
+    out = []
+    for t in tokens:
+        t = t.strip().lower().rstrip(".")
+        t = idxmap.get(t, t)
+        if t in ("a", "b", "c", "d") and t not in out:
+            out.append(t)
+    return out
+
+
+def parse_interactive_block(src: str) -> dict:
+    inner = re.sub(r'^\s*<!--\s*互動\s*-->\s*', '', src, flags=re.S)
+    inner = re.sub(r'<!---?\s*互動end\s*-->\s*$', '', inner, flags=re.S)
+
+    m_fill_zh = re.search(r'<!--\s*填空([^>]*)-->(.*?)<!--\s*填空end\s*-->', inner, re.S)
+    m_fill_en = re.search(r'<!--\s*fill([^>]*)-->(.*?)<!--\s*fill(?:_end|end)\s*-->', inner, re.S)
+    m_fill    = m_fill_en or m_fill_zh
+    m_mcq_old = re.search(r'<!--\s*選擇([^>]*)-->(.*?)<!--\s*選擇end\s*-->', inner, re.S)
+    m_mcq_new = re.search(r'<!--\s*(?:mcq|choice)([^>]*)-->(.*?)<!--\s*(?:mcq|choice)(?:_end|end)\s*-->', inner, re.S)
+    m_mcq     = m_mcq_new or m_mcq_old
+
+    beg = min([m.start() for m in [m_fill, m_mcq] if m] or [len(inner)])
+    prompt_md   = inner[:beg].rstrip()
+    prompt_runs: list[dict] = []
+    if prompt_md:
+        for part in _BLANKPARA_SPLIT.split(prompt_md):
+            if not part: continue
+            if _BLANKPARA_SPLIT.fullmatch(part):
+                _append_blankline_runs(part, prompt_runs)
+            else:
+                runs = parse_paragraph_runs_color_aware(part) or []
+                for r in runs: r['newline'] = 'false'
+                prompt_runs.extend(runs)
+
+    if m_fill:
+        attrs   = _attrs_to_dict(m_fill.group(1) or "")
+        body    = (m_fill.group(2) or "").strip()
+        right   = attrs.get("right", ""); wrong = attrs.get("wrong", "")
+        ans     = attrs.get("ans") or (body.splitlines()[0].strip() if body else "")
+        answers = [s.strip() for s in ans.split("|") if s.strip()]
+        normalize = [s.strip() for s in (attrs.get("normalize") or "sym,numeric,nospace").split(",") if s.strip()]
+        if not prompt_runs and body:
+            for p_idx, para in enumerate(re.split(r'\n\s*\n', body)):
+                runs = parse_paragraph_runs_color_aware(para)
+                is_last = (p_idx == len(re.split(r'\n\s*\n', body)) - 1)
+                for r in runs: r.setdefault("newline", "false" if is_last else "true")
+                prompt_runs.extend(runs)
+        return {
+            "type": "quiz", "qtype": "fill", "id": attrs.get("id", ""),
+            "prompt_runs": prompt_runs, "answers": answers, "normalize": normalize,
+            "placeholder": attrs.get("placeholder", ""), "border": attrs.get("border", "1"),
+            "inline_math": attrs.get("inline_math", "1"), "right_msg": right, "wrong_msg": wrong,
+            "card": attrs.get("card", "1"),
+        }
+
+    if m_mcq:
+        attrs  = _attrs_to_dict(m_mcq.group(1) or "")
+        body   = (m_mcq.group(2) or "").strip()
+        right  = attrs.get("right", ""); wrong = attrs.get("wrong", "")
+        hints  = {}
+        for k, v in attrs.items():
+            kk = (k or "").strip().lower()
+            if kk.startswith("hint_"):
+                opt = kk.split("_", 1)[1].strip().lower()
+                if opt in ("a", "b", "c", "d") and str(v).strip():
+                    hints[opt] = str(v).strip()
+        indent_flag = attrs.get("indent") or attrs.get("indent_options")
+        lines = body.splitlines()
+        lead_lines, opt_lines, seen_option = [], [], False
+        for ln in lines:
+            t = ln.strip()
+            if re.match(r'^[aAdDbBcC]\s*\.', t):
+                seen_option = True; opt_lines.append(t)
+            else:
+                (opt_lines if seen_option else lead_lines).append(ln)
+        if not prompt_runs and lead_lines:
+            paragraphs = re.split(r'\n\s*\n', "\n".join(lead_lines).rstrip())
+            for p_idx, para in enumerate(paragraphs):
+                runs = parse_paragraph_runs_color_aware(para)
+                is_last = (p_idx == len(paragraphs) - 1)
+                for r in runs: r.setdefault("newline", "false" if is_last else "true")
+                prompt_runs.extend(runs)
+        opts = []
+        for t in (opt_lines if opt_lines else lines):
+            tt = t.strip()
+            for key, pat in [("a", r'^[aA]\s*\.'), ("b", r'^[bB]\s*\.'), ("c", r'^[cC]\s*\.'), ("d", r'^[dD]\s*\.')]:
+                if re.match(pat, tt):
+                    opts.append({"key": key, "text": tt.split('.', 1)[1].strip()})
+        multi_flag = attrs.get("multi") or attrs.get("multiple") or attrs.get("checkbox")
+        is_multi   = str(multi_flag).strip().lower() in ("1", "true", "yes", "y", "on")
+        ans_raw    = (attrs.get("ans", "") or "").strip().lower().rstrip(".")
+        ans_list   = _split_mcq_answers(ans_raw)
+        ans_one    = ans_list[0] if ans_list else ""
+        node = {
+            "type": "quiz", "qtype": "multi" if is_multi else "choice",
+            "id": attrs.get("id", ""), "prompt_runs": prompt_runs, "options": opts,
+            "shuffle": attrs.get("shuffle", "0") in ("1", "true", "yes"),
+            "explain": attrs.get("explain", ""), "right_msg": right, "wrong_msg": wrong,
+            "wrong_hints": hints, "card": attrs.get("card", "1"),
+        }
+        if is_multi:
+            node["answers"] = ans_list; node["answer"] = ""
+        else:
+            node["answer"] = ans_one
+        if indent_flag is not None:
+            node["indent_options"] = indent_flag
+        return node
+
+    return {"type": "paragraph", "content": prompt_md, "runs": prompt_runs}
+
+
+def _next_flow_id() -> str:
+    global _FLOW_SEQ
+    _FLOW_SEQ += 1
+    return f"flow-{_FLOW_SEQ}"
+
+
+def parse_flow_block(src: str) -> dict:
+    m = _FLOW_RE.search(src)
+    if not m:
+        return {"type": "paragraph", "content": src}
+    fattrs  = _attrs_to_dict(m.group("attrs") or "")
+    body    = (m.group("body") or "").strip()
+    flow_id = fattrs.get("id") or _next_flow_id()
+    persist = (fattrs.get("persist") or "").strip()
+
+    steps_raw = list(_STEP_RE.finditer(body))
+    if not steps_raw:
+        steps_raw_iter = [("", body)]
+        def _unwrap(x): return x[0], x[1]
+    else:
+        steps_raw_iter = steps_raw
+        def _unwrap(mm): return (mm.group("attrs") or ""), (mm.group("body") or "").strip()
+
+    steps, quiz_seq, prev_gate_qid = [], 0, None
+    for i, raw in enumerate(steps_raw_iter, start=1):
+        sattrs_raw, sbody = _unwrap(raw)
+        sattrs    = _attrs_to_dict(sattrs_raw)
+        step_id   = sattrs.get("id") or f"step-{i}"
+        title     = sattrs.get("title") or f"步驟 {i}"
+        cond      = (sattrs.get("cond") or "all").lower().strip()
+        content_blocks = parse_document(sbody)
+        first_quiz_id  = None
+        for b in content_blocks:
+            if b.get("type") == "quiz":
+                if not b.get("id"):
+                    quiz_seq += 1
+                    b["id"] = f"{flow_id}::{step_id}::q{quiz_seq}"
+                b["flow"] = flow_id; b["step"] = step_id
+                if first_quiz_id is None:
+                    first_quiz_id = b["id"]
+        steps.append({"id": step_id, "title": title, "cond": cond, "content": content_blocks, "gate_from": prev_gate_qid})
+        if first_quiz_id is not None:
+            prev_gate_qid = first_quiz_id
+
+    return {"type": "flow", "id": flow_id, "persist": persist, "steps": steps}
+
+
+def parse_solution_block(src: str) -> dict:
+    m_open  = _SOL_OPEN.search(src)
+    m_close = _SOL_CLOSE.search(src, m_open.end() if m_open else 0)
+    if not (m_open and m_close):
+        return {"type": "paragraph", "content": src}
+
+    attrs_raw = (m_open.group("attrs") or "").strip()
+    shortcut_label = ""
+    attrs_for_dict = attrs_raw
+    m_short = re.match(r'^_([^\s]+)(.*)$', attrs_raw)
+    if m_short:
+        shortcut_label = (m_short.group(1) or "").strip()
+        attrs_for_dict = (m_short.group(2) or "").strip()
+    attrs  = _attrs_to_dict(attrs_for_dict)
+    inner  = src[m_open.end():m_close.start()]
+    body_blocks = [b for b in parse_document(inner) if b.get('type') != 'comment']
+
+    label   = ((attrs.get("label") or shortcut_label or "").strip()) or "看解法"
+    default = (attrs.get("default", "closed") or "closed").lower()
+    persist = (attrs.get("persist", "none") or "none").lower()
+    card    = str(attrs.get("card", "0"))
+    accent  = attrs.get("accent", "")
+    after   = attrs.get("after", "")
+
+    h = hashlib.md5()
+    for part in [inner, label, default, persist, card, accent, after]:
+        h.update((part or "").encode("utf-8"))
+        h.update(b"|")
+    uid = f"sol_{h.hexdigest()[:10]}"
+
+    return {
+        "type": "solution", "uid": uid, "label": label,
+        "default": default, "persist": persist, "card": card,
+        "accent": accent, "after": after, "body": body_blocks,
+    }
+
+
+def parse_quizzes(md: str) -> list[dict]:
+    """解析 <!--quiz ...--> ... <!--quiz_end--> 區塊（order 題型）。"""
+    out, i = [], 0
+    while True:
+        m = QUIZ_OPEN.search(md, i)
+        if not m: break
+        n = QUIZ_END.search(md, m.end())
+        if not n: break
+        block   = md[m.end():n.start()]
+        attrs   = _parse_attrs(m.group('attrs') or "")
+        qtype   = (attrs.get("qtype") or "").strip().lower() or "multi"
+        title   = (attrs.get("title") or "練習題").strip()
+        card    = 1 if str(attrs.get("card", "1")).lower() in ("1", "true", "yes") else 0
+        shuffle = str(attrs.get("shuffle", "0")).lower() in ("1", "true", "yes")
+        prompt_md = ""
+        for ln in block.splitlines():
+            s = ln.strip()
+            if s and not s.startswith("<!--"):
+                prompt_md = s; break
+        if qtype == "order":
+            steps = [s.strip() for s in STEP_RE_SIMPLE.findall(block)]
+            qid   = (attrs.get("id") or _slug_ascii(title, "order"))
+            out.append({
+                "type": "quiz", "qtype": "order", "id": qid,
+                "title": title, "card": card, "shuffle": shuffle,
+                "prompt_md": prompt_md, "steps": steps, "answer": list(range(len(steps))),
+                "msg_right": attrs.get("msg_right") or "✔ 正確！",
+                "msg_wrong": attrs.get("msg_wrong") or "✘ 再想想。",
+            })
+        i = n.end()
+    return out
+
+# ---------------------------------------------------------------------------
+# 段落 block 解析（核心）
+# ---------------------------------------------------------------------------
+
+def parse_content_block(text: str) -> list[dict]:
+    return _parse_plain_blocks(text)
+
+
+def _parse_plain_blocks(text: str) -> list[dict]:
+    parsed_content: list[dict] = []
+    pattern = r'(^\s*#+.*?\n|\n{2,}|^\s*[-_]{3,}\s*$)'
+    blocks  = re.split(pattern, text, flags=re.MULTILINE | re.DOTALL)
+
+    for block_text in blocks:
+        m_blank = re.fullmatch(r'\s*\n{2,}\s*', block_text, flags=re.DOTALL)
+        if m_blank:
+            for _ in range(max(1, block_text.count('\n') - 1)):
+                _emit_blank_paragraph(parsed_content)
+            continue
+        if not block_text:
+            continue
+
+        heading_match = re.match(r'^\s*#+', block_text)
+        if heading_match:
+            level = len(heading_match.group(0).strip())
+            has_newline   = block_text.endswith('\n')
+            clean_content = re.sub(r'^\s*#+\s*', '', block_text).strip()
+            runs = build_inline_runs(clean_content)
+            # 標題預設套 teal
+            if not any(('color' in r) or ('color_light' in r) or ('color_dark' in r) for r in runs):
+                for r in runs:
+                    r['color'] = 'teal'; r['color_light'] = 'teal'; r['color_dark'] = "#49F0C3"
+                    attach_theme_colors(r)
+            node = {
+                'type': 'heading', 'level': level,
+                'content': _plain_text_from_runs(runs),
+                'newline': 'true' if has_newline else 'false', 'runs': runs,
+            }
+            if len(runs) == 1:
+                if 'color' in runs[0]: node['color'] = runs[0]['color']
+                if 'style' in runs[0]: node['style'] = runs[0]['style']
+            parsed_content.append(node)
+            continue
+
+        elif re.match(r'^\s*([*-]|\d+\.)\s+', block_text):
+            parsed_content.append({'type': 'list', 'content': parse_list_items(block_text)})
+
+        elif re.fullmatch(r'^\s*([-]{3,}|[_-]{3,})\s*$', block_text, re.DOTALL):
+            parsed_content.append({'type': 'horizontal_rule', 'content': block_text.strip()})
+
+        else:
+            ITEM_LINE  = re.compile(r'(?m)^\s*(?:[*-]|\d+\.)\s+')
+            first_item = ITEM_LINE.search(block_text)
+            if first_item and len(ITEM_LINE.findall(block_text)) >= 2:
+                preface = block_text[:first_item.start()]
+                rest    = block_text[first_item.start():]
+                m_end   = re.search(r'\n\s*\n(?!\s*(?:[*-]|\d+\.)\s+)', rest)
+                if m_end:
+                    list_src = rest[:m_end.start()]; tail = rest[m_end.end():]
+                else:
+                    list_src = rest; tail = ""
+                if preface.strip():
+                    runs = parse_paragraph_runs_color_aware(preface)
+                    parsed_content.append({
+                        'type': 'paragraph', 'content': _plain_text_from_runs(runs),
+                        'newline': 'true' if _has_newline_token(runs) else 'false', 'runs': runs,
+                    })
+                parsed_content.append({'type': 'list', 'content': parse_list_items(list_src)})
+                if tail.strip():
+                    parsed_content.extend(_parse_plain_blocks(tail))
+                continue
+
+            para_text    = block_text
+            m_file_only  = _FILE_MARKER_RE.fullmatch(para_text.strip())
+            if m_file_only:
+                parsed_content.append({"type": "file_embed", "relpath": (m_file_only.group("path") or "").strip()})
+                continue
+
+            nodes    = _split_text_links_images(para_text)
+            buf_runs: list[dict] = []
+
+            def flush_buf():
+                nonlocal buf_runs
+                if buf_runs:
+                    parsed_content.append({
+                        'type': 'paragraph',
+                        'content': _plain_text_from_runs(buf_runs),
+                        'newline': 'true' if _has_newline_token(buf_runs) else 'false',
+                        'runs': buf_runs,
+                    })
+                    buf_runs = []
+
+            for node in nodes:
+                if node["type"] == "text":
+                    for part in _split_text_and_ggb(node["content"]):
+                        if part["kind"] == "ggb":
+                            flush_buf()
+                            parsed_content.append(_ggb_node_from_attrs(part["attrs"]))
+                        else:
+                            buf_runs.extend(parse_paragraph_runs_color_aware(part["text"]))
+                elif node["type"] == "URL":
+                    flush_buf()
+                    parsed_content.append({'type': 'URL', 'text': node['text'], 'href': node['href']})
+                elif node["type"] == "picture":
+                    flush_buf()
+                    parsed_content.append({'type': 'picture', 'alt': node['alt'], 'src': node['src']})
+            flush_buf()
+
+    return parsed_content
+
+# ---------------------------------------------------------------------------
+# 文件級解析
+# ---------------------------------------------------------------------------
+
+def parse_document(entire_markdown_text: str, *, root_md: str = "") -> list[dict]:
+    """
+    最頂層解析器：識別所有特殊區塊（card/solution/quiz/flow/ggb...），
+    其餘文字交給 parse_content_block。
+
+    root_md：整份原始 MD（供 AI prompt 用）；若空則用 entire_markdown_text。
+    """
+    _full_md = root_md or _ROOT_MD or entire_markdown_text
+
+    parsed_results: list[dict] = []
+    last_match_end = 0
+
+    pattern = re.compile(
+        r'<!--\s*flow[^>]*-->.*?<!--\s*flow_end\s*-->|'
+        r'<!--\s*quiz[^>]*-->.*?<!--\s*quiz_end\s*-->|'
+        r'<!--\s*card[^>]*-->.*?<!--\s*card_end\s*-->|'
+        r'<!--\s*solution[^>]*-->.*?<!--\s*solution_end\s*-->|'
+        r'<!--\s*pyfunc[^>]*-->|'
+        r'<!--CH\d+-P\d+-->|'
+        r'<!--\s*互動\s*-->.*?<!---?\s*互動end\s*-->|'
+        r'<!--\s*選擇[^>]*-->.*?<!--\s*選擇end\s*-->|'
+        r'<!--\s*(?:mcq|choice)[^>]*-->.*?<!--\s*(?:mcq|choice)(?:_end|end)\s*-->|'
+        r'<!--\s*填空[^>]*-->.*?<!--\s*填空end\s*-->|'
+        r'<!--\s*fill[^>]*-->.*?<!--\s*fill(?:_end|end)\s*-->|'
+        r'<!--\s*problem[^>]*-->|'
+        r'^\s*<!--\s*icon[^>]*-->\s*$|'
+        r'<!--\s*ggb[^>]*-->',
+        re.DOTALL,
+    )
+
+    for match in re.finditer(pattern, entire_markdown_text):
+        start, end = match.span()
+        pre_text = entire_markdown_text[last_match_end:start]
+        if pre_text:
+            parsed_results.extend(parse_content_block(pre_text))
+        content = match.group(0)
+
+        if content.lstrip().startswith('<!--card'):
+            parsed_results.append(parse_card_block(content))
+        elif content.lstrip().startswith('<!--solution'):
+            sol_node = parse_solution_block(content)
+            if isinstance(sol_node, dict) and sol_node.get("type") == "solution":
+                ai_md = build_ai_prompt_for_solution_pos(_full_md, start)
+                if ai_md:
+                    sol_node["ai_prompt_md"] = ai_md
+            parsed_results.append(sol_node)
+        elif content.lstrip().startswith('<!--CH'):
+            parsed_results.append({'type': 'comment', 'content': content})
+        elif content.lstrip().startswith('<!--problem'):
+            parsed_results.append({'type': 'comment', 'content': content})
+        elif content.lstrip().startswith('<!--pyfunc'):
+            parsed_results.append(parse_pyfunc_marker(content))
+        elif re.match(r'^\s*<!--\s*(互動|選擇|填空|fill|choice|mcq)\b', content):
+            quiz_node = parse_interactive_block(content)
+            if isinstance(quiz_node, dict) and quiz_node.get("type") == "quiz":
+                ai_md = build_ai_prompt_for_pos(_full_md, start)
+                if ai_md:
+                    quiz_node["ai_prompt_md"] = ai_md
+            if not quiz_node.get('prompt_runs') and parsed_results:
+                i = len(parsed_results) - 1
+                while i >= 0 and parsed_results[i].get('type') == 'br':
+                    i -= 1
+                if i >= 0 and parsed_results[i].get('type') == 'paragraph':
+                    prev = parsed_results[i]
+                    runs = prev.get('runs') or build_inline_runs(prev.get('content', ''))
+                    if prev.get('problem_tag'):
+                        quiz_node['prompt_runs'] = runs
+                    else:
+                        prev = parsed_results.pop(i)
+                        quiz_node['prompt_runs'] = prev.get('runs') or build_inline_runs(prev.get('content', ''))
+            parsed_results.append(quiz_node)
+        elif content.lstrip().startswith('<!--quiz'):
+            parsed_results.extend(parse_quizzes(content))
+        elif content.lstrip().startswith('<!--flow'):
+            parsed_results.append(parse_flow_block(content))
+        elif content.lstrip().startswith('<!--icon'):
+            parsed_results.append(parse_icon_marker(content))
+        elif content.lstrip().startswith('<!--ggb'):
+            parsed_results.append(parse_geogebra_marker(content))
+        else:
+            parsed_results.append({'type': 'unknown', 'content': content})
+
+        last_match_end = end
+
+    tail_text = entire_markdown_text[last_match_end:]
+    if tail_text:
+        parsed_results.extend(parse_content_block(tail_text))
+
+    # 補 Example heading 的 example_seq + ai_prompt_md
+    example_seq = 0
+    for node in parsed_results:
+        if node.get("type") != "heading":
+            continue
+        level = int(node.get("level", 0) or 0)
+        txt   = (node.get("content") or "").strip()
+        if level == 3 and txt.lower().startswith("example"):
+            example_seq += 1
+            node["example_seq"] = example_seq
+            node["ai_prompt_md"] = build_ai_prompt_for_example(_full_md, example_seq)
+
+    return parsed_results

layout/converter/md_color.py

@@ -0,0 +1,166 @@
+"""
+md_color.py
+-----------
+顏色相關工具：CSS 命名色 → HEX、HEX ↔ HSL、亮暗色對計算。
+
+公開 API：
+    attach_theme_colors(run)   ← 主要對外接口，補齊 color_light / color_dark
+"""
+from __future__ import annotations
+import re
+
+# ---------------------------------------------------------------------------
+# 顏色標記 Regex（供 md_runs.py 使用）
+# ---------------------------------------------------------------------------
+COLOR_OPEN      = re.compile(r'<!--c_([A-Za-z0-9#]+)-->')
+COLOR_CLOSE_ANY = re.compile(r'<!--c_([A-Za-z0-9#]+)_end-->')
+
+# ---------------------------------------------------------------------------
+# CSS 命名色表
+# ---------------------------------------------------------------------------
+_CSS_NAMED_TO_HEX: dict[str, str] = {
+    "black": "#000000", "white": "#ffffff", "gray": "#808080", "grey": "#808080",
+    "silver": "#c0c0c0", "red": "#ff0000", "green": "#008000", "blue": "#0000ff",
+    "yellow": "#ffff00", "orange": "#ffa500", "brown": "#a52a2a", "purple": "#800080",
+    "violet": "#8a2be2", "indigo": "#4b0082", "pink": "#ffc0cb", "magenta": "#ff00ff",
+    "cyan": "#00ffff", "teal": "#008080", "lime": "#00ff00", "gold": "#ffd700",
+}
+
+# 特殊顏色例外對照（不走一般 HSL 公式）
+_COLOR_PAIR_TABLE: dict[str, tuple[str, str]] = {
+    "#0000ff": ("#A6B7FF", "#4DFFFF"),
+    "#4dffff": ("#4DFFFF", "#003B66"),
+}
+
+# ---------------------------------------------------------------------------
+# HEX 正規化
+# ---------------------------------------------------------------------------
+def _norm_hex(c: str) -> str:
+    """把 CSS 顏色值統一成 7 位 #rrggbb 格式；命名色也轉換。"""
+    if not isinstance(c, str):
+        return ""
+    s = c.strip()
+    if not s:
+        return ""
+    if s.startswith("#"):
+        if len(s) == 4:                          # #rgb → #rrggbb
+            return "#" + "".join(ch * 2 for ch in s[1:])
+        return s[:7] if len(s) >= 7 else s
+    lo = s.lower()
+    if lo in _CSS_NAMED_TO_HEX:
+        return _CSS_NAMED_TO_HEX[lo]
+    return s
+
+# ---------------------------------------------------------------------------
+# HEX ↔ HSL
+# ---------------------------------------------------------------------------
+def _hex_to_hsl(hx: str) -> tuple[float, float, float]:
+    hx = _norm_hex(hx)
+    if not (hx.startswith("#") and len(hx) == 7):
+        return (0.0, 0.0, 0.0)
+    r = int(hx[1:3], 16) / 255
+    g = int(hx[3:5], 16) / 255
+    b = int(hx[5:7], 16) / 255
+    mx, mn = max(r, g, b), min(r, g, b)
+    l = (mx + mn) / 2
+    if mx == mn:
+        return (0.0, 0.0, l)
+    d = mx - mn
+    s = d / (2 - mx - mn) if l > 0.5 else d / (mx + mn)
+    if mx == r:
+        h = (g - b) / d + (6 if g < b else 0)
+    elif mx == g:
+        h = (b - r) / d + 2
+    else:
+        h = (r - g) / d + 4
+    return (h / 6, s, l)
+
+
+def _hsl_to_hex(h: float, s: float, l: float) -> str:
+    def _f(p: float, q: float, t: float) -> float:
+        if t < 0: t += 1
+        if t > 1: t -= 1
+        if t < 1 / 6: return p + (q - p) * 6 * t
+        if t < 1 / 2: return q
+        if t < 2 / 3: return p + (q - p) * (2 / 3 - t) * 6
+        return p
+
+    if s == 0:
+        r = g = b = l
+    else:
+        q = l + s - l * s if l >= 0.5 else l * (1 + s)
+        p = 2 * l - q
+        r = _f(p, q, h + 1 / 3)
+        g = _f(p, q, h)
+        b = _f(p, q, h - 1 / 3)
+    return "#{:02x}{:02x}{:02x}".format(int(r * 255 + 0.5), int(g * 255 + 0.5), int(b * 255 + 0.5))
+
+# ---------------------------------------------------------------------------
+# 亮 / 暗色計算
+# ---------------------------------------------------------------------------
+def _to_dark_color(hex_light: str) -> str:
+    """把亮色調暗，作為 dark mode 用色。"""
+    hx_low = _norm_hex(hex_light).lower()
+    if hx_low in _COLOR_PAIR_TABLE:
+        _, dark_hint = _COLOR_PAIR_TABLE[hx_low]
+        if dark_hint:
+            return _norm_hex(dark_hint)
+    h, s, l = _hex_to_hsl(hex_light)
+    if l > 0.7:
+        l2 = 0.50
+    elif l > 0.55:
+        l2 = 0.46 + (l - 0.55) * 0.10
+    else:
+        l2 = max(0.42, l * 0.75 + 0.10)
+    return _hsl_to_hex(h, max(0.10, s * 0.80), l2)
+
+
+def _to_light_color(hex_dark: str) -> str:
+    """把暗色調亮，作為 light mode 用色。"""
+    h, s, l = _hex_to_hsl(hex_dark)
+    if l < 0.35:
+        l2 = min(0.82, l * 0.3 + 0.65)
+        s2 = max(0.10, s * 0.75)
+    else:
+        l2 = min(0.86, 1 - (1 - l) * 0.5)
+        s2 = max(0.10, s * 0.80)
+    return _hsl_to_hex(h, s2, l2)
+
+
+def _is_named_color(tok: str) -> bool:
+    return isinstance(tok, str) and tok.strip().lower() in _CSS_NAMED_TO_HEX
+
+# ---------------------------------------------------------------------------
+# 主要對外 API
+# ---------------------------------------------------------------------------
+def attach_theme_colors(run: dict) -> None:
+    """
+    根據 run 裡的 color / color_light / color_dark，
+    補齊 color_light 與 color_dark 兩個欄位（就地修改）。
+    """
+    if run.get("color_light") and run.get("color_dark"):
+        return
+    if run.get("color_light") and not run.get("color_dark"):
+        run["color_dark"] = _to_dark_color(run["color_light"])
+        return
+    if run.get("color_dark") and not run.get("color_light"):
+        run["color_light"] = _to_light_color(run["color_dark"])
+        return
+
+    col = run.get("color")
+    if not col:
+        return
+
+    if _is_named_color(col):
+        run["color_light"] = col
+        run["color_dark"] = _to_dark_color(_norm_hex(col))
+        return
+
+    c = _norm_hex(col)
+    _, _, L = _hex_to_hsl(c)
+    if L >= 0.5:
+        run["color_light"] = col
+        run["color_dark"] = _to_dark_color(c)
+    else:
+        run["color_dark"] = col
+        run["color_light"] = _to_light_color(c)

layout/converter/md_io.py

@@ -0,0 +1,202 @@
+"""
+md_io.py
+--------
+檔案讀寫與 build pipeline（最頂層，依賴全部其他模組）。
+
+公開 API：
+    build_from_config(config_path, force=False) → List[Path]
+"""
+from __future__ import annotations
+from pathlib import Path
+from typing import List
+import json
+
+from . import md_blocks  # 注入 _ROOT_MD 用
+from .md_blocks import (
+    parse_document,
+    assign_ids_and_build_toc,
+    split_blocks_into_sections,
+)
+
+# ---------------------------------------------------------------------------
+# 副檔名 → 語言對照
+# ---------------------------------------------------------------------------
+_EXT2LANG: dict[str, str] = {
+    ".py": "python", ".js": "javascript", ".ts": "typescript",
+    ".css": "css", ".html": "markup", ".md": "markdown",
+    ".json": "json", ".yml": "yaml", ".yaml": "yaml",
+    ".tex": "latex", ".r": "r", ".cpp": "cpp", ".c": "c",
+}
+
+# ---------------------------------------------------------------------------
+# 檔案嵌入工具
+# ---------------------------------------------------------------------------
+
+def _parse_file_spec(spec: str) -> tuple[str, str | None]:
+    spec = (spec or "").strip()
+    if "::" in spec:
+        p, f = spec.split("::", 1)
+        return p.strip(), (f.strip() or None)
+    return spec, None
+
+
+def _split_md_by_file_markers(md_text: str) -> list[tuple[str, str]]:
+    import re
+    FILE_MARKER_RE = re.compile(
+        r'<!--\s*file(?:_|[\s]+)(?P<path>[^>\r\n]+?)\s*-->', re.IGNORECASE
+    )
+    segs, pos = [], 0
+    for m in FILE_MARKER_RE.finditer(md_text or ""):
+        if m.start() > pos:
+            segs.append(("text", md_text[pos:m.start()]))
+        gd = m.groupdict() if hasattr(m, "groupdict") else {}
+        file_token = (gd.get("path") or "").strip()
+        if not file_token:
+            file_token = md_text[m.start():m.end()]
+        segs.append(("file", file_token))
+        pos = m.end()
+    if pos < len(md_text or ""):
+        segs.append(("text", md_text[pos:]))
+    return segs
+
+
+def _resolve_code_file(md_dir: Path, file_token: str) -> Path | None:
+    p = Path(file_token)
+    if not p.is_absolute():
+        p = (md_dir / file_token).resolve()
+        if not p.exists():
+            alt = (Path.cwd() / "assets" / "files" / file_token).resolve()
+            if alt.exists():
+                p = alt
+    return p if p.exists() and p.is_file() else None
+
+
+def _read_code_for_embed(p: Path, max_bytes: int = 300_000) -> tuple[str, str]:
+    ext  = p.suffix.lower()
+    lang = _EXT2LANG.get(ext, "text")
+    data = p.read_bytes()
+    note = ""
+    if len(data) > max_bytes:
+        data = data[:max_bytes]
+        note = f"\n\n# [truncated] file too large; showing first {max_bytes} bytes\n"
+    code = data.decode("utf-8", errors="replace") + note
+    return code, lang
+
+
+def _materialize_file_embeds(nodes: list[dict], base_dir: Path) -> list[dict]:
+    out: list[dict] = []
+    for n in nodes:
+        if not isinstance(n, dict):
+            out.append(n); continue
+        if n.get("type") == "file_embed":
+            file_token = (n.get("relpath") or "").strip()
+            p = _resolve_code_file(base_dir, file_token)
+            if not p:
+                out.append({"type": "code", "filename": file_token, "lang": "text",
+                            "code": f"# [missing] cannot locate file: {file_token}"})
+            else:
+                code, lang = _read_code_for_embed(p)
+                out.append({"type": "code", "filename": p.name, "path": str(p), "lang": lang, "code": code})
+        elif n.get("type") == "card":
+            n["body"] = _materialize_file_embeds(n.get("body") or [], base_dir)
+            out.append(n)
+        elif n.get("type") == "flow":
+            steps = []
+            for s in n.get("steps") or []:
+                s = dict(s)
+                s["content"] = _materialize_file_embeds(s.get("content") or [], base_dir)
+                steps.append(s)
+            n["steps"] = steps
+            out.append(n)
+        elif n.get("type") == "solution":
+            n["body"] = _materialize_file_embeds(n.get("body") or [], base_dir)
+            out.append(n)
+        else:
+            out.append(n)
+    return out
+
+# ---------------------------------------------------------------------------
+# 單檔轉換
+# ---------------------------------------------------------------------------
+
+def _export_one(md_path: Path, out_path: Path) -> Path:
+    text   = md_path.read_text(encoding="utf-8")
+    md_dir = md_path.parent
+
+    md_blocks._ROOT_MD = text
+
+    segments = _split_md_by_file_markers(text)
+    blocks: list[dict] = []
+
+    for kind, payload in segments:
+        if kind == "text":
+            if payload.strip():
+                blocks.extend(parse_document(payload, root_md=text))
+        else:
+            file_token, func = _parse_file_spec(payload)
+            p = _resolve_code_file(md_dir, file_token)
+            if not p:
+                blocks.append({"type": "code", "filename": file_token, "lang": "text",
+                               "code": f"# [missing] cannot locate file: {file_token}"})
+            else:
+                code, lang = _read_code_for_embed(p)
+                if func:
+                    blocks.append({"type": "pycall", "filename": p.name, "path": str(p),
+                                   "func": func, "lang": lang, "code": code})
+                else:
+                    blocks.append({"type": "code", "filename": p.name, "path": str(p),
+                                   "lang": lang, "code": code})
+
+    blocks   = _materialize_file_embeds(blocks, md_dir)
+    toc      = assign_ids_and_build_toc(blocks)
+    sections = split_blocks_into_sections(blocks)
+
+    payload  = {"toc": toc, "blocks": blocks, "sections": sections}
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    out_path.write_text(json.dumps(payload, ensure_ascii=False, indent=4), encoding="utf-8")
+    return out_path
+
+# ---------------------------------------------------------------------------
+# Build pipeline（對外 API）
+# ---------------------------------------------------------------------------
+
+def build_from_config(
+    config_path: str | Path,
+    force: bool = False,
+) -> List[Path]:
+    cfgp = Path(config_path).resolve()
+    base = cfgp.parent
+    cfg  = json.loads(cfgp.read_text(encoding="utf-8"))
+
+    up_to_date = False if force else bool(cfg.get("up_to_date", True))
+    outputs: List[Path] = []
+
+    for t in cfg.get("tasks", []):
+        md  = (base / t["md"]).resolve()
+        out = (base / t["out"]).resolve()
+
+        if not md.exists():
+            raise FileNotFoundError(f"[build] Markdown not found: {md}")
+
+        need = True
+        if not force and up_to_date and out.exists():
+            need = md.stat().st_mtime > out.stat().st_mtime
+
+        if need or not out.exists():
+            p = _export_one(md, out)
+            print(f"[build] wrote: {p}")
+        else:
+            print(f"[build] up-to-date: {out}")
+            p = out
+
+        outputs.append(p)
+
+    return outputs
+
+
+if __name__ == "__main__":
+    import sys
+    if len(sys.argv) >= 2:
+        build_from_config(sys.argv[1])
+    else:
+        print("Usage: python md_io.py <config.json>")

layout/converter/md_pipeline.py

@@ -0,0 +1,101 @@
+"""
+Test2ChMd.py  ← 向下相容 shim
+-------------------------------
+原始 2097 行已拆分至以下六個模組（均放在同一 layout/ 資料夾下）：
+
+    md_color.py   顏色工具
+    md_tex.py     TeX 分隔符
+    md_attrs.py   屬性解析
+    md_runs.py    行內 run 組裝
+    md_blocks.py  block / 文件解析
+    md_io.py      I/O + build pipeline
+
+此 shim 重新匯出所有公開 API，確保現有程式碼不需要修改：
+
+    from layout.Test2ChMd import build_from_config   ← 仍可用
+    from layout.Test2ChMd import parse_document      ← 仍可用
+"""
+
+# ── Layer 0：顏色 ──────────────────────────────────────────────────────────
+from .md_color import (                         # noqa: F401
+    attach_theme_colors,
+    _norm_hex,
+    _hex_to_hsl, _hsl_to_hex,
+    _to_dark_color, _to_light_color,
+    _is_named_color,
+    _CSS_NAMED_TO_HEX,
+    _COLOR_PAIR_TABLE,
+)
+
+# ── Layer 0：TeX ──────────────────────────────────────────────────────────
+from .md_tex import (                           # noqa: F401
+    _strip_outer_tex_delims,
+    _ensure_inline_dollars,
+    _ensure_block_dollars,
+)
+
+# ── Layer 0：屬性解析 ──────────────────────────────────────────────────────
+from .md_attrs import (                         # noqa: F401
+    _attrs_to_dict,
+    _parse_attrs,
+    _slug_ascii,
+)
+
+# ── Layer 1-2：行內 run ────────────────────────────────────────────────────
+from .md_runs import (                          # noqa: F401
+    split_color_runs,
+    split_math_runs,
+    split_emphasis_runs,
+    normalize_runs,
+    build_inline_runs,
+    emit_text_runs_color_aware,
+    _has_newline_token,
+    _plain_text_from_runs,
+    _append_hard_break,
+    _materialize_hard_break_tokens,
+    _split_text_and_any_display_math,
+    _split_text_and_icon,
+    _split_text_links_images,
+    _split_text_and_ggb,
+)
+
+# ── Layer 2-5：block / 文件解析 ────────────────────────────────────────────
+from .md_blocks import (                        # noqa: F401
+    # 段落 / 清單
+    parse_line_color_aware,
+    parse_paragraph_runs_color_aware,
+    parse_list_items,
+    _emit_blank_paragraph,
+    _append_blankline_runs,
+    _split_midline_new_item,
+    # 特殊 marker
+    parse_geogebra_marker,
+    parse_icon_marker,
+    parse_pyfunc_marker,
+    parse_card_block,
+    parse_interactive_block,
+    parse_flow_block,
+    parse_solution_block,
+    parse_quizzes,
+    # 頂層
+    parse_content_block,
+    parse_document,
+    # TOC / sections
+    assign_ids_and_build_toc,
+    split_blocks_into_sections,
+    # AI prompt
+    build_ai_prompt_for_example,
+    build_ai_prompt_for_pos,
+    build_ai_prompt_for_solution_pos,
+)
+
+# ── Layer 6：I/O ───────────────────────────────────────────────────────────
+from .md_io import (                            # noqa: F401
+    build_from_config,
+    _export_one,
+    _parse_file_spec,
+    _split_md_by_file_markers,
+    _resolve_code_file,
+    _read_code_for_embed,
+    _EXT2LANG,
+)

layout/converter/md_runs.py

@@ -0,0 +1,338 @@
+"""
+md_runs.py
+----------
+行內 run（inline run）的切分、組裝與正規化。
+
+依賴：md_color, md_tex, md_attrs（相對 import）
+
+公開 API：
+    build_inline_runs(text)              → List[run]   主要入口
+    emit_text_runs_color_aware(text, cs) → List[run]
+    normalize_runs(runs)                 → List[run]
+    split_color_runs(text)               → List[run]
+    split_math_runs(text)                → List[run]
+    split_emphasis_runs(text)            → List[run]
+    _has_newline_token(runs)             → bool
+    _plain_text_from_runs(runs)          → str
+    _append_hard_break(runs)             → None
+    _materialize_hard_break_tokens(runs) → runs
+    _split_text_and_any_display_math(s)  → List[dict]
+    _split_text_and_icon(text)           → List[tuple]
+    _split_text_links_images(line)       → List[dict]
+    _split_text_and_ggb(s)              → List[dict]
+"""
+from __future__ import annotations
+import re
+
+from .md_color import attach_theme_colors, COLOR_OPEN, COLOR_CLOSE_ANY
+from .md_tex   import _ensure_inline_dollars, _ensure_block_dollars
+from .md_attrs import _attrs_to_dict
+
+# ---------------------------------------------------------------------------
+# 正規表達式
+# ---------------------------------------------------------------------------
+_SPLIT_DOLLAR2 = re.compile(r'(\$\$.*?\$\$)', re.S)
+_WRAP_DOLLAR2  = re.compile(r'^\s*\$\$(.*?)\$\$\s*$', re.S)
+
+_GGB_ANY_RE    = re.compile(r'<!--\s*ggb(?P<attrs>[^>]*)-->')
+_ICON_INLINE_RE = re.compile(r'<!--\s*icon(?P<attrs>[^>]*)-->', re.I)
+
+_IMG_RE        = re.compile(r'!\[([^\]]*)\]\(([^)\s]+)\)')
+_LINK_RE       = re.compile(r'(?<!!)\[([^\]]+)\]\(([^)\s]+)\)')
+
+_MATH_INLINE_RE = re.compile(
+    r'(?<!\\)(?<!\$)\$(?!\$)(.+?)(?<!\\)(?<!\$)\$(?!\$)'
+    r'|(\\dfrac\{[^{}]+\}\{[^{}]+\})',
+    re.DOTALL,
+)
+_EMPH_RE = re.compile(
+    r'(\*{3}[^\n*]+?\*{3}|\*{2}[^\n*]+?\*{2}|\*[^\n*]+?\*)'
+)
+_COLOR_TAG = re.compile(r'<!--c_([A-Za-z0-9#]+)-->|\s*<!--c_([A-Za-z0-9#]+)_end-->')
+
+# ---------------------------------------------------------------------------
+# 文字切分工具
+# ---------------------------------------------------------------------------
+
+def _split_text_and_any_display_math(s: str) -> list[dict]:
+    parts = _SPLIT_DOLLAR2.split(s or "")
+    out = []
+    for p in parts:
+        if not p: continue
+        m = _WRAP_DOLLAR2.match(p)
+        if m:
+            out.append({"kind": "math_block", "latex": _ensure_block_dollars(m.group(1).strip())})
+        else:
+            out.append({"kind": "text", "text": p})
+    return out
+
+
+def _split_text_and_icon(text: str) -> list[tuple[str, str]]:
+    parts, pos = [], 0
+    for m in _ICON_INLINE_RE.finditer(text):
+        if m.start() > pos:
+            parts.append(("text", text[pos:m.start()]))
+        parts.append(("icon", m.group(0)))
+        pos = m.end()
+    if pos < len(text):
+        parts.append(("text", text[pos:]))
+    return parts
+
+
+def _split_text_links_images(line: str) -> list[dict]:
+    nodes, i = [], 0
+    img_matches = list(_IMG_RE.finditer(line))
+    img_spans   = [(m.start(), m.end()) for m in img_matches]
+    matches     = [("img", m.start(), m.end(), m) for m in img_matches]
+    for m in _LINK_RE.finditer(line):
+        st, ed = m.start(), m.end()
+        if any(st >= a and ed <= b for a, b in img_spans):
+            continue
+        matches.append(("a", st, ed, m))
+    if not matches:
+        return [{"type": "text", "content": line}]
+    matches.sort(key=lambda x: x[1])
+    for kind, start, end, m in matches:
+        if start > i:
+            chunk = line[i:start]
+            if chunk:
+                nodes.append({"type": "text", "content": chunk})
+        if kind == "img":
+            nodes.append({"type": "picture", "alt": m.group(1).strip(), "src": m.group(2).strip()})
+        else:
+            nodes.append({"type": "URL", "text": m.group(1).strip(), "href": m.group(2).strip()})
+        i = end
+    if i < len(line):
+        tail = line[i:]
+        if tail:
+            nodes.append({"type": "text", "content": tail})
+    return nodes
+
+
+def _split_text_and_ggb(s: str) -> list[dict]:
+    out, i = [], 0
+    for m in _GGB_ANY_RE.finditer(s or ""):
+        if m.start() > i:
+            out.append({"kind": "text", "text": s[i:m.start()]})
+        attrs = _attrs_to_dict(m.group("attrs") or "")
+        out.append({"kind": "ggb", "attrs": attrs})
+        i = m.end()
+    if i < len(s or ""):
+        out.append({"kind": "text", "text": s[i:]})
+    return out
+
+# ---------------------------------------------------------------------------
+# Run 切分器
+# ---------------------------------------------------------------------------
+
+def split_color_runs(text: str) -> list[dict]:
+    runs, i = [], 0
+    while True:
+        m_open = COLOR_OPEN.search(text, i)
+        if not m_open:
+            if i < len(text):
+                runs.append({"text": text[i:]})
+            break
+        if m_open.start() > i:
+            runs.append({"text": text[i:m_open.start()]})
+        name = m_open.group(1)
+        m_close = re.compile(rf'<!--c_{re.escape(name)}_end-->').search(text, m_open.end())
+        if not m_close:
+            runs.append({"text": text[m_open.start():]})
+            break
+        inner = text[m_open.end():m_close.start()]
+        runs.append({"text": inner, "color": name})
+        i = m_close.end()
+    return runs
+
+
+def split_math_runs(text: str) -> list[dict]:
+    from .md_blocks import parse_icon_marker
+
+    runs, i = [], 0
+    for m in _MATH_INLINE_RE.finditer(text or ""):
+        if m.start() > i:
+            before = text[i:m.start()]
+            for k2, frag in _split_text_and_icon(before):
+                if k2 == "text":
+                    if frag: runs.append({"text": frag})
+                else:
+                    icon_info = parse_icon_marker(frag)
+                    runs.append({"kind": "icon", "icon": icon_info.get("icon", ""), "height": icon_info.get("height", "18")})
+
+        latex = (m.group(1) or m.group(2) or "").strip()
+        runs.append({"latex": _ensure_inline_dollars(latex), "kind": "math"})
+        i = m.end()
+
+    if i < len(text or ""):
+        from .md_blocks import parse_icon_marker as _pim
+        tail = text[i:]
+        for k2, frag in _split_text_and_icon(tail):
+            if k2 == "text":
+                if frag: runs.append({"text": frag})
+            else:
+                icon_info = _pim(frag)
+                runs.append({"kind": "icon", "icon": icon_info.get("icon", ""), "height": icon_info.get("height", "18")})
+
+    return runs
+
+
+def split_emphasis_runs(text: str) -> list[dict]:
+    runs, i = [], 0
+    for m in _EMPH_RE.finditer(text):
+        if m.start() > i:
+            runs.append({"text": text[i:m.start()]})
+        chunk = m.group(0)
+        if chunk.startswith("***") and chunk.endswith("***"):
+            runs.append({"text": chunk[3:-3], "style": "bold-italic"})
+        elif chunk.startswith("**") and chunk.endswith("**"):
+            runs.append({"text": chunk[2:-2], "style": "bold"})
+        elif chunk.startswith("*") and chunk.endswith("*"):
+            runs.append({"text": chunk[1:-1], "style": "italic"})
+        else:
+            runs.append({"text": chunk})
+        i = m.end()
+    if i < len(text):
+        runs.append({"text": text[i:]})
+    return runs
+
+# ---------------------------------------------------------------------------
+# Run 正規化與組裝
+# ---------------------------------------------------------------------------
+
+def normalize_runs(runs: list[dict]) -> list[dict]:
+    out: list[dict] = []
+    for r in runs:
+        if "latex" in r and r.get("kind") in ("math", "math_block"):
+            out.append(r); continue
+        if r.get("newline") == "true" and "text" not in r:
+            out.append({"newline": "true"}); continue
+        if r.get("kind") == "icon":
+            out.append(r); continue
+
+        t = r.get("text", "")
+        if t == "":
+            continue
+
+        style = r.get("style")
+        color = r.get("color")
+        cl    = r.get("color_light")
+        cd    = r.get("color_dark")
+        prev  = out[-1] if out else None
+        can_merge = (
+            prev is not None
+            and "latex" not in prev
+            and prev.get("kind") != "icon"
+            and prev.get("newline") != "true"
+            and "text" in prev
+            and prev.get("style") == style
+            and prev.get("color") == color
+        )
+        if can_merge:
+            prev["text"] += t
+            if cl and "color_light" not in prev: prev["color_light"] = cl
+            if cd and "color_dark"  not in prev: prev["color_dark"]  = cd
+        else:
+            keep = ("color", "style", "color_light", "color_dark")
+            out.append({"text": t, **{k: r[k] for k in keep if k in r}})
+
+    for rr in out:
+        attach_theme_colors(rr)
+    return out
+
+
+def build_inline_runs(text: str) -> list[dict]:
+    out: list[dict] = []
+    for cr in split_color_runs(text):
+        base_color = cr.get("color")
+        for er in split_emphasis_runs(cr["text"]):
+            style = er.get("style")
+            seg   = er["text"]
+            for mr in split_math_runs(seg):
+                if mr.get("kind") == "icon":
+                    run = {"kind": "icon", "icon": mr.get("icon", ""), "height": mr.get("height", 18)}
+                elif "latex" in mr:
+                    run = {"latex": mr["latex"], "kind": "math"}
+                    if style: run["style"] = style
+                else:
+                    run = {"text": mr.get("text", "")}
+                    if style: run["style"] = style
+                if base_color: run["color"] = base_color
+                out.append(run)
+
+    runs = normalize_runs(out)
+    for r in runs:
+        attach_theme_colors(r)
+    return runs
+
+
+def emit_text_runs_color_aware(text: str, color_stack: list) -> list[dict]:
+    runs_out, i, s = [], 0, (text or "")
+    while i <= len(s):
+        m_open  = COLOR_OPEN.search(s, i)
+        m_close = COLOR_CLOSE_ANY.search(s, i)
+        if m_open and m_close:
+            ev  = m_open if m_open.start() < m_close.start() else m_close
+            typ = "open" if ev is m_open else "close"
+        else:
+            ev  = m_open or m_close
+            typ = "open" if ev is m_open else ("close" if m_close else None)
+
+        j       = ev.start() if ev else len(s)
+        visible = s[i:j]
+        if visible:
+            seg_runs = build_inline_runs(visible)
+            if color_stack:
+                for r in seg_runs:
+                    r["color"] = color_stack[-1]
+                    attach_theme_colors(r)
+            runs_out.extend(seg_runs)
+
+        if not ev: break
+        name = ev.group(1)
+        if typ == "open":
+            color_stack.append(name)
+        else:
+            if color_stack and color_stack[-1] == name: color_stack.pop()
+            else:
+                try: color_stack.remove(name)
+                except ValueError: pass
+        i = ev.end()
+    return runs_out
+
+# ---------------------------------------------------------------------------
+# Run 工具函式
+# ---------------------------------------------------------------------------
+
+def _has_newline_token(runs: list[dict]) -> bool:
+    return any(r.get("newline") == "true" and "text" not in r for r in runs)
+
+
+def _plain_text_from_runs(runs: list[dict]) -> str:
+    parts = []
+    for r in runs:
+        if r.get("newline") == "true" and "text" not in r:
+            parts.append("\n"); continue
+        if "latex" in r:
+            if r.get("kind") == "math":
+                parts.append(_ensure_inline_dollars(r.get("latex", "")))
+            elif r.get("kind") in ("math_block", "block_math", "display_math"):
+                parts.append(_ensure_block_dollars(r.get("latex", "")))
+            else:
+                parts.append(r.get("latex", ""))
+        else:
+            parts.append(r.get("text", ""))
+    return "".join(parts)
+
+
+def _append_hard_break(runs: list[dict]) -> None:
+    if runs and runs[-1].get("newline") == "true" and "text" not in runs[-1]:
+        return
+    runs.append({"newline": "true"})
+
+
+def _materialize_hard_break_tokens(runs: list[dict]) -> list[dict]:
+    for r in runs:
+        if "text" in r and r["text"]:
+            r["text"] = r["text"].replace("  \r\n", "\n").replace("  \n", "\n")
+    return runs

layout/converter/md_tex.py

@@ -0,0 +1,50 @@
+"""
+md_tex.py
+---------
+LaTeX 分隔符正規化工具。
+
+公開 API：
+    _strip_outer_tex_delims(s)   → (core_latex, kind)
+    _ensure_inline_dollars(s)    → "$core$"
+    _ensure_block_dollars(s)     → "$$\ncore\n$$"
+"""
+from __future__ import annotations
+import re
+
+# ---------------------------------------------------------------------------
+# 正規表達式
+# ---------------------------------------------------------------------------
+_re_outer_block  = re.compile(r'^\s*\${2}(.*)\${2}\s*$', re.S)
+_re_outer_inline = re.compile(r'^\s*\$(.*)\$\s*$', re.S)
+
+# ---------------------------------------------------------------------------
+# 公開函式
+# ---------------------------------------------------------------------------
+def _strip_outer_tex_delims(s: str) -> tuple[str, str]:
+    """
+    移除最外層的 TeX 分隔符。
+
+    回傳 (core_latex, kind)，kind 為 "block" / "inline" / "none"。
+    """
+    if s is None:
+        return "", "none"
+    t = str(s).strip()
+    m = _re_outer_block.match(t)
+    if m:
+        return m.group(1).strip(), "block"
+    m = _re_outer_inline.match(t)
+    if m:
+        return m.group(1).strip(), "inline"
+    return t, "none"
+
+
+def _ensure_inline_dollars(s: str) -> str:
+    """確保字串以 $...$ 包裹（行內數學）。"""
+    core, _ = _strip_outer_tex_delims(s)
+    return f"${core}$"
+
+
+def _ensure_block_dollars(s: str) -> str:
+    """確保字串以 $$....$$ 包裹（區塊數學）。"""
+    core, _ = _strip_outer_tex_delims(s)
+    return f"$$\n{core}\n$$"

layout/generate_common_card.py

@@ -0,0 +1,38 @@
+"""
+layout/generate_common_card.py  ← 遷移橋接（shim）
+----------------------------------------------------
+此檔案已廢棄，請改從 components.cards 匯入。
+
+    舊：from layout.generate_common_card import generate_custom_markdown_card
+    新：from components.cards import generate_custom_markdown_card
+
+    舊：from layout.generate_common_card import render_card_from_node
+    新：from components.cards import render_card_from_node
+
+此 shim 讓舊 import 繼續正常運作，不影響現有頁面。
+待所有頁面完成遷移後，直接刪除此檔即可。
+"""
+import warnings
+warnings.warn(
+    "layout.generate_common_card 已廢棄，請改用 components.cards",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
+from components.cards import (          # noqa: F401
+    generate_custom_markdown_card,
+    render_card_from_node,
+)
+from components.render_utils import (   # noqa: F401
+    _inline_math,
+    _block_math,
+    _runs_to_children,
+)
+
+__all__ = [
+    "generate_custom_markdown_card",
+    "render_card_from_node",
+    "_inline_math",
+    "_block_math",
+    "_runs_to_children",
+]

layout/page/__init__.py

@@ -0,0 +1,5 @@
+"""
+page/ — 頁面組裝
+外部可直接用：from layout.page import make_test_page
+"""
+from .page_layout import make_test_page  # noqa: F401