From 30a861f910ddcbc2a473a56342afbd92dcd96792 Mon Sep 17 00:00:00 2001
From: xfy <i@rua.plus>
Date: Fri, 26 Jun 2026 14:07:42 +0800
Subject: [PATCH] =?UTF-8?q?docs(agents):=20=E6=96=B0=E5=A2=9E=20yggdrasil-?=
 =?UTF-8?q?core=20=E5=AD=90=E5=B7=A5=E7=A8=8B=E7=AB=A0=E8=8A=82?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

与 lightbox/tiptap-editor 并列,记录用途、构建、注入方式与
主题展开动画的 View Transitions 实现。同步更新 make test 注释
与 Build Artifacts 列表。
---
 AGENTS.md    | 19 ++++++++++++++++---
 src/theme.rs |  5 +++++
 2 files changed, 21 insertions(+), 3 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index f9213a4..2ebb69a 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -15,7 +15,7 @@ make build         # build-editor → highlight-css → tailwindcss → doc →
 make build-linux   # same as build but targets x86_64-unknown-linux-musl
 make css           # one-shot CSS
 make css-watch     # watch mode
-make test          # cargo test + vitest (tiptap-editor + lightbox libs)
+make test          # cargo test + vitest (tiptap-editor + lightbox + yggdrasil-core libs)
 make doc           # cargo doc (ayu 主题) → 拷贝到 public/doc/，随 build 发布
 make doc-open      # 同 doc，生成后自动用浏览器打开（本地预览，不拷贝）
 make clean         # cargo clean + rm public/style.css
@@ -150,6 +150,18 @@ Image lightbox (click-to-zoom) in `libs/lightbox/`, built as an IIFE library. Un
 
 Do not edit `public/lightbox/` — they are build artifacts.
 
+## Yggdrasil-Core Subproject
+
+Core JavaScript bundle in `libs/yggdrasil-core/`, built as an IIFE library exposing `window.__initPostContent` and `window.__startThemeTransition` (and future core JS entry points). This is the designated home for all new core JS — add to it rather than creating new `public/js/` scripts.
+
+- Output: `public/yggdrasil-core/` (`yggdrasil-core.js`, `yggdrasil-core.css`, `yggdrasil-core.js.map`)
+- `make build` runs `npm ci --include=dev && npm run build` inside `libs/yggdrasil-core`; the `build` script is `tsc --noEmit && vite build` (Vite 8 / Rolldown, type-check before bundle). Source is ES module, output is IIFE (`formats: ['iife']` in `vite.config.ts`) because Dioxus `[web.resource] script` injects bare `<script src>` without `type="module"` support.
+- Injected globally via `Dioxus.toml` (`script` + `style` arrays). Rust calls the entry points via `js_sys::eval("window.__xxx(...)")` with an `if (window.__xxx)` guard to survive script-load ordering races.
+- Unit tests: `npm test` (Vitest 4 + happy-dom), covering `post-content` copy-button lifecycle and `theme-transition` fallback paths (happy-dom lacks `startViewTransition`, naturally covering the degradation path).
+- Theme reveal animation uses the View Transitions API: JS synchronously toggles the `dark` class inside `startViewTransition`'s callback (so the browser snapshots the new state), CSS `@keyframes tt-reveal` expands `::view-transition-new(root)` via `clip-path: circle()` from the click point; Rust's `theme.set()` aligns state afterward (idempotent — `use_effect` sets the same class again). `prefers-reduced-motion` and browsers without VT fall back to instant switch.
+
+Do not edit `public/yggdrasil-core/` — they are build artifacts.
+
 ## Syntax Highlighting Pipeline
 
 - `themes/` contains Catppuccin Latte (light) and Mocha (dark) `.tmTheme` files
@@ -173,7 +185,7 @@ Do not edit `public/lightbox/` — they are build artifacts.
 ## Testing
 
 ```bash
-make test          # cargo test (Rust, 402 tests) + vitest (tiptap-editor 46 tests, lightbox 23 tests)
+make test          # cargo test (Rust, 402 tests) + vitest (tiptap-editor 46 tests, lightbox 23 tests, yggdrasil-core 9 tests)
 dx check          # Dioxus type-check (catches component/Router issues)
 cargo clippy      # lint
 ```
@@ -193,8 +205,9 @@ Most tests use `#[cfg(all(test, feature = "server"))]` — they only run when th
 - `public/highlight.css` — generated by `generate_highlight_css` binary
 - `public/tiptap/` — Vite build output (editor)
 - `public/lightbox/` — Vite build output (lightbox)
+- `public/yggdrasil-core/` — Vite build output (core JS bundle)
 - `/dist`, `/.dioxus`, `/target`
-- `node_modules` (inside `libs/tiptap-editor/` and `libs/lightbox/`)
+- `node_modules` (inside `libs/tiptap-editor/`, `libs/lightbox/`, and `libs/yggdrasil-core/`)
 - `uploads/.cache/` — image processing disk cache
 
 ## Notes
diff --git a/src/theme.rs b/src/theme.rs
index 0b70d94..b3d0c82 100644
--- a/src/theme.rs
+++ b/src/theme.rs
@@ -8,6 +8,8 @@
 use dioxus::prelude::*;
 // InteractionLocation 提供 client_coordinates(),用于读取鼠标点击的视口坐标。
 // 该 trait 不在 dioxus::prelude(后者只 re-export events::*),需单独从 dioxus::html 引入。
+// 仅 WASM 前端用到(ThemeToggle 的圆形展开动画取点击坐标),服务端构建剥离。
+#[cfg(target_arch = "wasm32")]
 use dioxus::html::InteractionLocation;
 
 /// localStorage 中存储主题值的键名。
@@ -158,6 +160,9 @@ pub fn ThemePreload() -> Element {
 }
 
 /// 主题切换按钮组件。
+// evt 仅在 wasm32 的圆形展开动画里使用(取点击坐标),服务端构建剥离,
+// 故允许非 wasm 构建下的 unused_variables(与 Write 组件同模式)。
+#[cfg_attr(not(target_arch = "wasm32"), allow(unused_variables))]
 #[component]
 pub fn ThemeToggle() -> Element {
     let mut theme = use_theme();