minecodex 2.0.2 → 2.0.3

package/packages/runtime-host/src/codex-runtime.mjs

@@ -1,4 +1,4 @@
-import { cloudImagesAction } from "./cloud-images.mjs";
+import { cloudImagesAction } from "../../../features/images/src/backend/cloud-library.mjs";
 // CodexRuntime：Codex Renderer 生命周期与 host action 执行。
 // 注入源（createInjectionSource）与 CDP 客户端分别在 codex-injection.mjs / codex-cdp.mjs。
 
@@ -32,7 +32,8 @@ import {
   attachFilesToComposer,
   createImageEditThread,
 } from "./host-actions.mjs";
-import { SessionStatusReader, threadIdFromLocation } from "./session-status-reader.mjs";
+import { SitesService } from "../../../features/sites/src/backend/sites-service.mjs";
+import { SessionStatusReader, threadIdFromLocation } from "../../../features/session-status/src/adapters/codex/session-reader.mjs";
 
 
 // 保持公共入口兼容：历史 import 从本文件继续可用。
@@ -73,9 +74,11 @@ export class CodexRuntime {
     featureInstanceId = null,
     runtimeSessionId = randomBytes(16).toString("hex"),
     onStatusChange = null,
+    sitesService = null,
     onManagedCodexPidChange = null,
   }) {
     this.features = features;
+    this.sitesService = sitesService ?? (features.some(feature => feature.id === "sites") ? new SitesService() : null);
     this.profileDir = profileDir;
     this.appPath = appPath;
     this.cdpPort = cdpPort;
@@ -546,6 +549,15 @@ export class CodexRuntime {
       });
       return;
     }
+    if (feature.id === "sites" && request.action === "sites") {
+      try {
+        const result = await this.sitesService.action(request.payload);
+        await this.resolveHostAction(client, request.requestId, { ok: true, result });
+      } catch (error) {
+        await this.resolveHostAction(client, request.requestId, { ok: false, error: { code: "SITES_REQUEST_FAILED", message: error.message } });
+      }
+      return;
+    }
     if (feature.id === "notes" && request.action === "quick-prompts") {
       try {
         const { route, method = "GET", body } = request.payload ?? {};
@@ -575,7 +587,12 @@ export class CodexRuntime {
     }
     if (["list-cloud-images", "import-cloud-image"].includes(request.action)) {
       try {
-        let result = await cloudImagesAction(client, request.action === "list-cloud-images" ? "list" : "import", request.payload);
+        let result = await cloudImagesAction(
+          async (expression, options) => evaluationValue(await client.send("Runtime.evaluate", {
+            expression, awaitPromise:true, returnByValue:true,
+          }, options)),
+          request.action === "list-cloud-images" ? "list" : "import", request.payload,
+        );
         if (request.action === "import-cloud-image" && !result.skipped) {
           result = await this.importGeneratedImage(feature, result);
         }
@@ -791,6 +808,7 @@ export class CodexRuntime {
   }
 
   async stop() {
+    this.sitesService?.launcher?.stop();
     if (this.stopPromise) return this.stopPromise;
     this.stopPromise = (async () => {
       this.stopping = true;

package/packages/runtime-host/src/feature-registry.mjs

@@ -3,9 +3,11 @@ import { spawn } from "node:child_process";
 import { readdir, readFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
+import { pathToFileURL } from "node:url";
 
 const MANIFEST_NAME = "codex-feature.json";
 const HOST_ACTIONS = new Set([
+  "sites",
   "quick-prompts",
   "insert-text",
   "attach-file",
@@ -177,11 +179,34 @@ async function normalizePageScript(manifest, projectDir) {
   if (relative.startsWith("..") || path.isAbsolute(relative)) {
     throw new Error("page-script resource must stay inside the feature project");
   }
-  const source = await readFile(scriptPath, "utf8");
-  if (!source.trim()) {
+  let source = await readFile(scriptPath, "utf8");
+  const factory = manifest.entry?.sourceFactory;
+  if (factory) {
+    const factoryPath = path.resolve(projectDir, factory);
+    const relativeFactory = path.relative(projectDir, factoryPath);
+    if (relativeFactory.startsWith("..") || path.isAbsolute(relativeFactory)) {
+      throw new Error("page-script source factory must stay inside the feature project");
+    }
+    const { createPageScriptSource } = await import(pathToFileURL(factoryPath).href);
+    if (typeof createPageScriptSource !== "function") throw new Error("page-script source factory must export createPageScriptSource");
+    source = await createPageScriptSource();
+  }
+  if (typeof source !== "string" || !source.trim()) {
     throw new Error("page-script resource must be a non-empty script file");
   }
-  return { resource, source };
+  // 资源随脚本一次传入 Renderer，不增加 HTTP 加载或模块闭包依赖。
+  const resources = {};
+  for (const [name, file] of Object.entries(manifest.entry?.resources ?? {})) {
+    if (typeof file !== "string") throw new Error("page-script resources must be file paths");
+    const resourcePath = path.resolve(projectDir, file);
+    const relativeResource = path.relative(projectDir, resourcePath);
+    if (relativeResource.startsWith("..") || path.isAbsolute(relativeResource)) {
+      throw new Error("page-script resources must stay inside the feature project");
+    }
+    const content = await readFile(resourcePath, "utf8");
+    resources[name] = file.endsWith(".json") ? JSON.parse(content) : content;
+  }
+  return { resource, source, resources };
 }
 
 async function normalizeFeature(manifest, projectDir, env) {

package/packages/ui/DESIGN.md

@@ -0,0 +1,31 @@
+# MineCodex UI 组件库的局部约定
+
+通用视觉与原生适配规则只维护在根 [DESIGN.md](../../DESIGN.md)。内部文档与代码路由见根 [AGENTS.md](../../AGENTS.md)，架构见 [ARCHITECTURE.md](ARCHITECTURE.md)。
+
+本级只负责共享组件自身的结构、接入与实现边界，不维护另一份颜色、字体、材质、遮罩或sidebar规则。
+
+## 当前阶段
+
+`packages/ui` 已建立独立私有 workspace，组件、token、安装源码与验证均在本级维护；实际目录见架构文档。未使用的原生组件分支不会仅因规范列出而预建空壳。
+
+## 组件职责
+
+- 原生适配层：解析实际token、主题、zoom和能力状态；共享锚点仅包含真实跨插件需求。原生事实遵循根规范，不在每个组件重新猜测。
+- 材质与层级基础：按Dialog、Dropdown、Popover、ComposerMenu、Page的原生分支提供有限选项，将遮罩与Portal规则同所选组件匹配。
+- Dialog：提供容器、标题、Close及操作区的结构；插件填表单、列表或确认内容。
+- Button：表达操作角色和状态，保留Cancel ghost、实际次级outline与主操作solid的语义区分；业务动作由插件传入。
+- Navbar：使用成对 default/selected 图标管理展示状态；原生图标与选中状态适配集中在 native 层，保留原生路由与 sidebar hover。
+- Tooltip：处理声明式标记、hover/focus、aria关联、关闭与卸载，不接管原生Tooltip。
+- 页面、菜单与浮层：提供对应类型的外壳、挂载和通用交互，不读取提示词、会话或站点业务数据。
+
+## 接入约束
+
+当前page-script通过 `config.ui` 使用公共能力；现有API包括 `heading`、`footer`、`action`、`overlay`、`surface`。`surface(node, kind, options)` 显式区分原生材质；`page`、`mount`、`trapFocus`、`composerMenu`、`tooltipSurface`、`navigationRail` 维护实际复用的层级、焦点与定位。`entry.resources` 通过 `config.resources` 提供插件自身 CSS 与图标，通用视觉仍由组件库维护。
+
+Renderer安装函数经序列化注入，必须自包含。组件代码与Node/CDP隔离，宿主负责组装注入源码、生命周期和iframe主题桥；不为整理目录引入不必要的打包系统。
+
+通用生命周期契约由组件库维护。原生已经提供的焦点圈定、Escape和关闭机制优先复用；插件继续拥有业务状态、内容更新和具体回调。迁移时同步触发点焦点恢复、异步卸载及原生节点归属验证。
+
+## 验证边界
+
+组件验证关注可注入性、结构与回调、状态清理、挂载/焦点以及所选原生类型的实际行为，不镜像每条CSS写实现测试。布局、材质和原生状态变化按风险做隔离验收；只移动文件时验证导入、序列化、发布名单与已有功能回归。

package/packages/ui/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "@minecodex/ui",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "Shared native design contracts and injectable UI for MineCodex.",
+  "scripts": { "test": "node --test test/*.test.mjs" }
+}

package/packages/ui/src/components/button.mjs

@@ -0,0 +1,21 @@
+// 随组件库组装为自包含 Renderer 安装函数。
+export function installButton(signal, ui) {
+  const style = document.createElement("style");
+  style.setAttribute("data-minecodex-ui-styles", "installButton");
+  style.textContent = `    [data-mcx-ui-surface=dialog] [data-mcx-ui-footer] { display:flex; flex-wrap:wrap; justify-content:flex-end; gap:12px; margin-top:12px; }
+    [data-mcx-ui-surface=dialog] [data-mcx-ui-footer]>button { display:inline-flex; align-items:center; justify-content:center; gap:var(--mcx-button-gap-lg); height:var(--mcx-control-size-lg); flex-shrink:0; padding:0 calc(var(--mcx-control-gutter-md) * var(--mcx-control-gutter-pill-scaling)); border:0; border-radius:var(--mcx-radius-full); font:inherit; font-size:var(--mcx-control-font-size-md); font-weight:400; line-height:1; white-space:nowrap; color:var(--mcx-color-text-primary); background:transparent; box-shadow:inset 0 0 0 1px var(--mcx-color-border-primary-outline); cursor:var(--cursor-interaction); }
+    [data-mcx-ui-surface=dialog] [data-mcx-ui-footer]>button:hover:not(:disabled):not([aria-disabled=true]) { background:var(--mcx-color-background-primary-outline-hover); }
+    [data-mcx-ui-surface=dialog] [data-mcx-ui-footer]>[data-mcx-ui-action=ghost] { color:var(--mcx-color-text-secondary); box-shadow:none; }
+    [data-mcx-ui-surface=dialog] [data-mcx-ui-footer]>[data-mcx-ui-action=ghost]:hover:not(:disabled):not([aria-disabled=true]) { background:var(--mcx-color-background-primary-ghost-hover); }
+    [data-mcx-ui-surface=dialog] [data-mcx-ui-footer]>[data-mcx-ui-action=primary] { box-shadow:none; background:var(--mcx-color-background-primary-solid); color:var(--mcx-color-text-primary-solid); }
+    [data-mcx-ui-surface=dialog] [data-mcx-ui-footer]>[data-mcx-ui-action=primary]:hover:not(:disabled):not([aria-disabled=true]) { background:var(--mcx-color-background-primary-solid-hover); }
+    [data-mcx-ui-surface=dialog] [data-mcx-ui-footer]>[data-mcx-ui-action=danger] { box-shadow:none; background:var(--mcx-color-background-danger-soft-alpha); color:var(--mcx-color-text-danger); }
+    [data-mcx-ui-surface=dialog] [data-mcx-ui-footer]>[data-mcx-ui-action=danger]:hover:not(:disabled):not([aria-disabled=true]) { background:var(--mcx-color-background-danger-soft-alpha-hover); }
+    [data-mcx-ui-surface=dialog] button:disabled { opacity:.4; cursor:default; }
+    [data-mcx-ui-surface=dialog] [data-mcx-ui-close]:focus-visible, [data-mcx-ui-surface=dialog] [data-mcx-ui-footer]>button:focus-visible { outline:2px solid var(--mcx-color-ring); outline-offset:0; }
+  `;
+  document.head.append(style);
+  signal.addEventListener("abort", () => style.remove(), { once:true });
+  const mark = (node, role, value = "") => { node.setAttribute(`data-mcx-ui-${role}`, value); return node; };
+  return { footer:node=>mark(node,"footer"), action:(node,tone="secondary")=>mark(node,"action",tone) };
+}

package/packages/ui/src/components/composer-menu.mjs

@@ -0,0 +1,18 @@
+// 与原生 Add 一样锚定输入框主体；diff 与请求队列不参与位置计算。
+export function installComposerMenu(signal, ui) {
+  return {
+    composerMenu(node, anchor, { gap = 4, maxHeight = 400 } = {}) {
+      const body = anchor.closest("[data-composer-body]");
+      if (!body) throw new Error("Composer body is unavailable");
+      ui.surface(node, "composer-menu");
+      ui.layer(node, "floating");
+      const rect = body.getBoundingClientRect();
+      const zoom = Number.parseFloat(getComputedStyle(node).zoom) || 1;
+      node.style.left = `${rect.left / zoom}px`;
+      node.style.top = `${(rect.top - gap) / zoom}px`;
+      node.style.width = `${rect.width / zoom}px`;
+      node.style.maxHeight = `${Math.max(0, Math.min(maxHeight, (rect.top - 16) / zoom))}px`;
+      return node;
+    },
+  };
+}

package/packages/ui/src/components/dialog.mjs

@@ -0,0 +1,55 @@
+// 随组件库组装为自包含 Renderer 安装函数。
+export function installDialog(signal, ui) {
+  const style = document.createElement("style");
+  style.setAttribute("data-minecodex-ui-styles", "installDialog");
+  style.textContent = `    [data-mcx-ui-surface=dialog]:not(dialog) { position:relative; }
+    [data-mcx-ui-surface=dialog] { box-sizing:border-box; padding:var(--mcx-modal-container-inner-padding); border:0; border-radius:var(--mcx-radius-3xl); corner-shape:round; color:var(--mcx-color-text-primary); font-family:var(--mcx-font-sans-default); font-size:var(--mcx-text-base); line-height:1.5; outline:none; }
+    [data-mcx-ui-surface=dialog] [data-mcx-ui-heading] { display:flex; align-items:center; gap:8px; padding-right:28px; margin:0 0 12px; }
+    [data-mcx-ui-surface=dialog] [data-mcx-ui-heading] h2 { flex:1; min-width:0; margin:0; font-size:var(--mcx-text-heading-md); line-height:1.4; font-weight:var(--mcx-font-weight-semibold); letter-spacing:normal; overflow:hidden; text-overflow:ellipsis; white-space:nowrap; }
+    [data-mcx-ui-surface=dialog] [data-mcx-ui-close] { position:absolute; top:16px; right:16px; display:flex; align-items:center; justify-content:center; width:24px; height:24px; padding:4px; border:0; border-radius:4px; background:transparent; color:color-mix(in srgb,var(--mcx-color-text-primary) 80%,transparent); cursor:var(--cursor-interaction); }
+    [data-mcx-ui-surface=dialog] [data-mcx-ui-close] svg { display:block; width:16px; height:16px; }
+    [data-mcx-ui-surface=dialog] [data-mcx-ui-close]:hover { background:var(--mcx-color-background-primary-ghost-hover); }
+  `;
+  document.head.append(style);
+  signal.addEventListener("abort", () => style.remove(), { once:true });
+  function heading(container, { title, closeLabel, onClose, back, variant = "opaque" }) {
+    ui.surface(container, "dialog", { variant });
+    const header = document.createElement("div");
+    header.setAttribute("data-mcx-ui-heading", "");
+    const h = document.createElement("h2"); h.textContent = title;
+    if (back) header.append(back);
+    header.append(h);
+    const close = document.createElement("button");
+    close.setAttribute("data-mcx-ui-close", "");
+    close.type = "button"; close.setAttribute("aria-label", closeLabel);
+    // 取自新版 Sites 原生 Close，保留其真实路径。
+    close.innerHTML = '<svg viewBox="0 0 21 21" fill="none" aria-hidden="true"><path d="M14.6549 5.57307C14.9283 5.2997 15.3718 5.2997 15.6451 5.57307C15.9185 5.84643 15.9185 6.28993 15.6451 6.5633L11.3903 10.8182L15.6451 15.0731L15.735 15.1834C15.9141 15.4551 15.8842 15.8242 15.6451 16.0633C15.4061 16.3024 15.0369 16.3322 14.7653 16.1531L14.6549 16.0633L10.4 11.8084L6.14515 16.0633C5.87178 16.3367 5.42828 16.3367 5.15492 16.0633C4.88155 15.7899 4.88155 15.3464 5.15492 15.0731L9.4098 10.8182L5.15492 6.5633L5.06507 6.45295C4.88597 6.18128 4.91584 5.81214 5.15492 5.57307C5.39399 5.33399 5.76313 5.30413 6.0348 5.48322L6.14515 5.57307L10.4 9.82795L14.6549 5.57307Z" fill="currentColor"/></svg>';
+    close.addEventListener("click", onClose);
+    container.append(header, close);
+    return header;
+  }
+  function trapFocus(getContainer, { onClose, isBlocked = () => false }) {
+    const controller = new AbortController();
+    const stop = () => { controller.abort(); signal.removeEventListener("abort", stop); };
+    signal.addEventListener("abort", stop, { once:true });
+    document.addEventListener("keydown", event => {
+      const container = getContainer();
+      if (!container || isBlocked()) return;
+      if (event.key === "Escape") {
+        event.preventDefault(); event.stopImmediatePropagation(); onClose(); return;
+      }
+      if (event.key !== "Tab") return;
+      const controls = [...container.querySelectorAll('button:not(:disabled),input:not(:disabled),select:not(:disabled),textarea:not(:disabled),[tabindex="0"]')]
+        .filter(node => !node.closest("[inert]") && node.getClientRects().length);
+      const first = controls[0], last = controls.at(-1);
+      if (!first) { event.preventDefault(); container.focus(); }
+      else if (event.shiftKey && (document.activeElement === first || document.activeElement === container)) {
+        event.preventDefault(); last.focus();
+      } else if (!event.shiftKey && (document.activeElement === last || document.activeElement === container)) {
+        event.preventDefault(); first.focus();
+      }
+    }, { signal:controller.signal, capture:true });
+    return stop;
+  }
+  return { heading, trapFocus };
+}

package/packages/ui/src/components/navigation-rail.mjs

@@ -0,0 +1,77 @@
+// 导航只覆盖展示状态；原生路由与 sidebar hover 行为仍由 Codex 管理。
+export function installNavigationRail(signal, ui, native) {
+  const snapshots = new Map();
+  const style = document.createElement("style");
+  style.setAttribute("data-minecodex-ui-styles", "navigation-rail");
+  style.textContent = `[data-mcx-native-rail-icon-hidden]{display:none!important}`;
+  document.head.append(style);
+  function restore() {
+    for (const [node, state] of snapshots) {
+      state.icon?.removeAttribute("data-mcx-native-rail-icon-hidden");
+      state.replacement?.remove();
+      if (!node.isConnected) continue;
+      for (const [name, value] of state.attributes) {
+        if (value === null) node.removeAttribute(name);
+        else node.setAttribute(name, value);
+      }
+    }
+    snapshots.clear();
+  }
+  function selection(button, selected) {
+    if (selected) {
+      if (!button.hasAttribute("data-selected")) button.setAttribute("data-selected", "");
+      if (button.getAttribute("aria-current") !== "page") button.setAttribute("aria-current", "page");
+    } else {
+      button.removeAttribute("data-selected");
+      button.removeAttribute("aria-current");
+    }
+    for (const glyph of button.querySelectorAll("[data-mcx-rail-glyph]")) {
+      glyph.style.display = glyph.getAttribute("data-mcx-rail-glyph") === (selected ? "selected" : "default") ? "" : "none";
+    }
+  }
+  function reconcile(button, selected) {
+    selection(button, selected);
+    if (!selected) restore();
+    const rail = button.closest("[data-app-navigation-rail]");
+    for (const node of rail?.querySelectorAll("[data-sidebar-destination]") ?? []) {
+      const icon = node.querySelector("svg:not([data-mcx-native-rail-icon])");
+      if (!icon) continue;
+      const item = native.item(node);
+      const active = item ? item.isCurrentDestination : node.getAttribute("aria-current") === "page";
+      if (!active && !snapshots.has(node)) native.remember(node, icon);
+      if (!selected || (!active && !node.hasAttribute("data-selected"))) continue;
+      let state = snapshots.get(node);
+      if (!state) {
+        state = { attributes:new Map(["data-selected", "aria-current", "data-suppress-active-style"]
+          .map(name => [name, node.getAttribute(name)])) };
+        snapshots.set(node, state);
+      }
+      if (active && state.icon !== icon) {
+        state.icon?.removeAttribute("data-mcx-native-rail-icon-hidden");
+        state.replacement?.remove();
+        state.icon = icon;
+        state.replacement = native.icon(node, icon);
+        if (state.replacement) {
+          state.replacement.setAttribute("data-mcx-native-rail-icon", "");
+          icon.after(state.replacement);
+          icon.setAttribute("data-mcx-native-rail-icon-hidden", "");
+        }
+      }
+      node.removeAttribute("data-selected");
+      node.removeAttribute("aria-current");
+      if (!node.hasAttribute("data-suppress-active-style")) node.setAttribute("data-suppress-active-style", "");
+    }
+  }
+  function navigationRail(button, { defaultIcon, selectedIcon }) {
+    defaultIcon.setAttribute("data-mcx-rail-glyph", "default");
+    selectedIcon.setAttribute("data-mcx-rail-glyph", "selected");
+    defaultIcon.setAttribute("aria-hidden", "true");
+    selectedIcon.setAttribute("aria-hidden", "true");
+    defaultIcon.after(selectedIcon);
+    button.setAttribute("data-minecodex-tooltip-side", "right");
+    selection(button, false);
+    return { select:selected => reconcile(button, selected), restore };
+  }
+  signal.addEventListener("abort", () => { restore(); style.remove(); }, { once:true });
+  return { navigationRail };
+}

package/packages/ui/src/components/page.mjs

@@ -0,0 +1,8 @@
+export function installPage(signal, ui) {
+  return {
+    page(node, { transparent = false } = {}) {
+      ui.surface(node, "page", { variant:transparent ? "transparent" : "opaque" });
+      return ui.layer(node, "page");
+    },
+  };
+}

package/packages/ui/src/components/tooltip.mjs

@@ -0,0 +1,96 @@
+// 自包含函数随运行时注入；只处理 MineCodex 标记，不接管原生 tooltip。
+export function installFeatureTooltips(signal) {
+  const attribute = "data-minecodex-tooltip";
+  const tip = document.createElement("div");
+  tip.id = "minecodex-feature-tooltip";
+  tip.setAttribute("role", "tooltip");
+  tip.hidden = true;
+  const style = document.createElement("style");
+  style.setAttribute("data-minecodex-ui-styles", "tooltip");
+  style.textContent = `
+    [data-mcx-ui-tooltip] { position:fixed;z-index:2147483001;pointer-events:none;box-sizing:border-box;
+      padding:calc(var(--mcx-spacing) * 1.25) calc(var(--mcx-spacing) * 3);border:1px solid var(--mcx-color-border-tooltip);border-radius:var(--mcx-radius-2xl);corner-shape:var(--mcx-codex-corner-shape);
+      background:var(--mcx-color-background-tooltip);color:var(--mcx-color-text-tooltip);box-shadow:var(--mcx-shadow-tooltip);
+      font-family:var(--mcx-font-sans-default);font-size:var(--mcx-text-sm);line-height:18px;
+      font-weight:var(--mcx-tooltip-compact-font-weight);letter-spacing:var(--mcx-tracking-tooltip);user-select:none; }
+  `;
+  document.head.append(style);
+  function tooltipSurface(node) { node.setAttribute("data-mcx-ui-tooltip", ""); return node; }
+  tooltipSurface(tip);
+  tip.style.cssText = `zoom:var(--codex-window-zoom,1);max-width:min(320px,calc(100vw - 16px));
+    text-align:center;overflow-wrap:anywhere;`;
+  let anchor = null;
+  let timer;
+  let frame;
+  let lastClosedAt = -Infinity;
+  function hide() {
+    clearTimeout(timer);
+    cancelAnimationFrame(frame);
+    if (anchor) {
+      const ids = (anchor.getAttribute("aria-describedby") || "").split(/\s+/).filter(id => id && id !== tip.id);
+      if (ids.length) anchor.setAttribute("aria-describedby", ids.join(" "));
+      else anchor.removeAttribute("aria-describedby");
+    }
+    if (!tip.hidden) lastClosedAt = Date.now();
+    anchor = null;
+    tip.hidden = true;
+  }
+  function position() {
+    if (!anchor?.isConnected || !anchor.getClientRects().length || anchor.getAttribute("aria-expanded") === "true") return hide();
+    const zoom = Number.parseFloat(getComputedStyle(tip).zoom) || 1;
+    const r = anchor.getBoundingClientRect();
+    const w = tip.offsetWidth, h = tip.offsetHeight;
+    // navbar 固定向右；普通控件跟随宿主的上下侧偏好，统一 2px 间距。
+    const side = anchor.getAttribute("data-minecodex-tooltip-side")
+      || (anchor.closest("[data-app-navigation-rail]") ? "right"
+        : getComputedStyle(anchor).getPropertyValue("--side-tooltip").trim() || "top");
+    const gap = 2 / zoom;
+    let x = (r.left + r.width / 2) / zoom - w / 2;
+    let y = side === "bottom" ? r.bottom / zoom + gap : r.top / zoom - h - gap;
+    if (side === "right" || side === "left") {
+      x = side === "right" ? r.right / zoom + gap : r.left / zoom - w - gap;
+      y = (r.top + r.height / 2) / zoom - h / 2;
+      if (x + w > innerWidth / zoom - 8) x = r.left / zoom - w - gap;
+      else if (x < 8) x = r.right / zoom + gap;
+    } else if (y < 8) y = r.bottom / zoom + gap;
+    else if (y + h > innerHeight / zoom - 8) y = r.top / zoom - h - gap;
+    tip.style.left = `${Math.max(8, Math.min(x, innerWidth / zoom - w - 8))}px`;
+    tip.style.top = `${Math.max(8, Math.min(y, innerHeight / zoom - h - 8))}px`;
+    frame = requestAnimationFrame(position);
+  }
+  function show(target, immediate = false) {
+    if (!target || target === anchor) return;
+    hide();
+    if (target.getAttribute("aria-expanded") === "true" || !target.getAttribute(attribute)) return;
+    anchor = target;
+    timer = setTimeout(() => {
+      if (!anchor?.isConnected) return hide();
+      if (!tip.isConnected) document.body.append(tip);
+      const theme = getComputedStyle(anchor);
+      for (const name of ["--radius-2xl", "--codex-corner-shape", "--color-background-tooltip", "--color-text-tooltip",
+        "--color-border-tooltip", "--shadow-tooltip", "--tooltip-compact-font-weight", "--tracking-tooltip",
+        "--spacing", "--text-sm", "--font-sans-default"]) {
+        const value = theme.getPropertyValue(name).trim();
+        if (value) tip.style.setProperty(name, value);
+        else tip.style.removeProperty(name);
+      }
+      tip.textContent = anchor.getAttribute(attribute);
+      tip.hidden = false;
+      const ids = (anchor.getAttribute("aria-describedby") || "").split(/\s+/).filter(Boolean);
+      anchor.setAttribute("aria-describedby", [...new Set([...ids, tip.id])].join(" "));
+      position();
+    }, immediate || Date.now() - lastClosedAt < 300 ? 0 : 200);
+  }
+  const targetOf = event => event.target instanceof Element ? event.target.closest(`[${attribute}]`) : null;
+  document.addEventListener("pointerover", event => show(targetOf(event)), { signal });
+  document.addEventListener("pointerout", event => {
+    if (anchor && !anchor.contains(event.relatedTarget)) hide();
+  }, { signal });
+  document.addEventListener("focusin", event => show(targetOf(event), true), { signal });
+  document.addEventListener("focusout", hide, { signal });
+  document.addEventListener("pointerdown", hide, { signal, capture: true });
+  document.addEventListener("keydown", event => { if (event.key === "Escape") hide(); }, { signal });
+  window.addEventListener("blur", hide, { signal });
+  signal.addEventListener("abort", () => { hide(); tip.remove(); style.remove(); }, { once: true });
+  return { tooltipSurface };
+}

package/packages/ui/src/foundation/layers.mjs

@@ -0,0 +1,14 @@
+// 挂载角色统一维护；模态 top layer 仍由原生 dialog 负责。
+export function installLayers(signal) {
+  const style = document.createElement("style");
+  style.setAttribute("data-minecodex-ui-styles", "layers");
+  style.textContent = `
+    [data-mcx-ui-layer=page] { position:fixed; z-index:20; }
+    [data-mcx-ui-layer=floating], [data-mcx-ui-layer=modal] { position:fixed; z-index:50; }
+  `;
+  document.head.append(style);
+  signal.addEventListener("abort", () => style.remove(), { once:true });
+  function layer(node, role) { node.setAttribute("data-mcx-ui-layer", role); return node; }
+  function mount(node, role, parent = document.body) { layer(node, role); parent.append(node); return node; }
+  return { layer, mount };
+}

package/packages/ui/src/foundation/surfaces.mjs

@@ -0,0 +1,34 @@
+// 材质按原生组件分支选择，定位和业务内容由调用方提供。
+export function installSurfaces(signal, ui) {
+  const style = document.createElement("style");
+  style.setAttribute("data-minecodex-ui-styles", "surfaces");
+  style.textContent = `
+    [data-mcx-ui-surface] { background:var(--mcx-color-surface-elevated-secondary); backdrop-filter:none; -webkit-backdrop-filter:none; }
+    [data-mcx-ui-surface=dialog] { box-shadow:0 0 0 .5px var(--mcx-color-border),var(--mcx-shadow-lg); }
+    [data-mcx-ui-surface=dialog][data-mcx-ui-variant=default] { background:color-mix(in oklab,var(--mcx-color-surface-elevated-secondary) 90%,transparent); backdrop-filter:blur(var(--mcx-blur-xl)); -webkit-backdrop-filter:blur(var(--mcx-blur-xl)); }
+    [data-mcx-ui-overlay], [data-mcx-ui-surface=dialog]::backdrop { background:var(--lightningcss-light,#e3e3e380) var(--lightningcss-dark,#00000080); backdrop-filter:var(--mcx-dialog-backdrop-fade-filter); -webkit-backdrop-filter:var(--mcx-dialog-backdrop-fade-filter); }
+    [data-mcx-ui-overlay=default], [data-mcx-ui-surface=dialog][data-mcx-ui-variant=default]::backdrop { background:var(--mcx-color-dialog-overlay); backdrop-filter:none; -webkit-backdrop-filter:none; }
+    [data-mcx-ui-surface=dropdown] { background:color-mix(in oklab,var(--mcx-color-surface-elevated-secondary) 90%,transparent); box-shadow:0 0 0 var(--mcx-dropdown-overlay-ring-width,.5px) var(--mcx-color-border-overlay),var(--mcx-shadow-dropdown-overlay,var(--mcx-shadow-xl-spread)); backdrop-filter:blur(var(--mcx-blur-sm)); -webkit-backdrop-filter:blur(var(--mcx-blur-sm)); }
+    [data-mcx-ui-surface=dropdown][data-mcx-ui-variant=opaque] { background:var(--mcx-color-surface-elevated-secondary); backdrop-filter:none; -webkit-backdrop-filter:none; }
+    [data-mcx-ui-surface=popover] { box-shadow:0 0 0 var(--mcx-popover-overlay-ring-width,.5px) var(--mcx-color-border-overlay),var(--mcx-shadow-popover-overlay,var(--mcx-shadow-lg)); }
+    [data-mcx-ui-surface=popover][data-mcx-ui-variant=translucent] { background:color-mix(in oklab,var(--mcx-color-surface-elevated-secondary) 90%,transparent); }
+    [data-mcx-ui-surface=composer-menu] { border:var(--mcx-suggestion-menu-border-width,1px) solid var(--mcx-color-border); border-radius:var(--mcx-radius-suggestion-menu,var(--mcx-radius-2xl)); box-shadow:var(--mcx-suggestion-menu-shadow,none); }
+    [data-mcx-ui-surface=page] { border-radius:var(--mcx-radius-xl-base); background:var(--mcx-color-surface); box-shadow:none; }
+    [data-mcx-ui-surface=page][data-mcx-ui-variant=transparent] { background:transparent; }
+  `;
+  document.head.append(style);
+  signal.addEventListener("abort", () => style.remove(), { once:true });
+  function surface(node, kind = "popover", { variant, opaque = true } = {}) {
+    const defaults = { dialog:"opaque", dropdown:"menu", popover:opaque ? "opaque" : "translucent", "composer-menu":"floating", page:"opaque" };
+    if (!(kind in defaults)) throw new Error(`Unknown UI surface: ${kind}`);
+    if (kind !== "dialog" && kind !== "page") ui.layer(node, "floating");
+    node.setAttribute("data-mcx-ui-surface", kind);
+    node.setAttribute("data-mcx-ui-variant", variant ?? defaults[kind]);
+    return node;
+  }
+  function overlay(node, variant = "opaque") {
+    node.setAttribute("data-mcx-ui-overlay", variant);
+    return node;
+  }
+  return { surface, overlay };
+}

package/packages/ui/src/install.mjs

@@ -0,0 +1,22 @@
+import { createNativeThemeAdapter } from "./native/theme.mjs";
+import { createNativeRailAdapter } from "./native/navigation-rail.mjs";
+import { installSurfaces } from "./foundation/surfaces.mjs";
+import { installLayers } from "./foundation/layers.mjs";
+import { installDialog } from "./components/dialog.mjs";
+import { installButton } from "./components/button.mjs";
+import { installPage } from "./components/page.mjs";
+import { installComposerMenu } from "./components/composer-menu.mjs";
+import { installNavigationRail } from "./components/navigation-rail.mjs";
+import { installFeatureTooltips } from "./components/tooltip.mjs";
+
+// 所有依赖在组装时显式写入源码，Renderer 不依赖 Node 模块闭包。
+export function createUIInstallerSource() {
+  const installers = [installSurfaces, installLayers, installDialog, installButton, installPage, installComposerMenu];
+  return `function installFeatureUI(signal, context) {
+    const ui = {theme:(${createNativeThemeAdapter.toString()})(context.themeTokens,context.themeTokenAliases,context.themeBindings)};
+    ${installers.map(install => `Object.assign(ui, (${install.toString()})(signal, ui));`).join("\n")}
+    Object.assign(ui, (${installNavigationRail.toString()})(signal, ui, (${createNativeRailAdapter.toString()})(context.codex)));
+    Object.assign(ui, (${installFeatureTooltips.toString()})(signal));
+    return ui;
+  }`;
+}

package/packages/ui/src/native/navigation-rail.mjs

@@ -0,0 +1,33 @@
+// 读取原生导航资源；不修改 React props，也不调用带 Hooks 的图标组件。
+export function createNativeRailAdapter(codex) {
+  const defaultIcons = new WeakMap();
+  function nativeItem(node) {
+    for (let fiber = codex.currentFiber(node); fiber; fiber = fiber.return) {
+      const item = fiber.memoizedProps?.item;
+      if (item?.id === node.getAttribute("data-sidebar-destination")) return item;
+    }
+    return null;
+  }
+  function defaultIcon(node, current) {
+    const item = nativeItem(node);
+    const resource = item?.railIcons?.default;
+    const factory = resource?.createElement ?? resource?.type?.createElement;
+    // 原生图标工厂显式暴露无 Hooks 的 DOM API，包含 optical 与主题处理。
+    if (factory) return factory(document, current.getAttribute("class") || "");
+    if (resource && resource === item.railIcons.selected) return current.cloneNode(true);
+    const asset = resource?.props?.asset;
+    // 新版原生 IconAsset 的单色资源可直接读取，不调用带 Hooks 的 React 组件。
+    if (asset?.paint?.kind === "monochrome" && typeof asset.body === "string") {
+      const svg = document.createElementNS("http://www.w3.org/2000/svg", "svg");
+      for (const [name, value] of Object.entries({ width:asset.canvas.width, height:asset.canvas.height,
+        viewBox:asset.canvas.viewBox, "aria-hidden":"true", class:current.getAttribute("class") || "" })) {
+        svg.setAttribute(name, String(value));
+      }
+      svg.innerHTML = asset.body;
+      return svg;
+    }
+    return defaultIcons.get(node)?.cloneNode(true) ?? null;
+  }
+  return { item:nativeItem, icon:defaultIcon,
+    remember:(node, icon) => defaultIcons.set(node, icon.cloneNode(true)) };
+}

package/packages/ui/src/native/theme.mjs

@@ -0,0 +1,35 @@
+// 将外部 token 名称解析为 MineCodex 变量；主题变化与卸载由此维护。
+export function createNativeThemeAdapter(themeTokenNames,themeTokenAliases,themeBindings) {
+  const previousThemeBindings=new Map();
+    function read() {
+      const root = document.documentElement;
+      const style = getComputedStyle(root);
+      const tokens = Object.fromEntries(
+        themeTokenNames
+          .map((name) => [name, style.getPropertyValue(name).trim()])
+          .filter(([, value]) => value),
+      );
+      // 按语义和命名空间解析，不依赖构建哈希或猜测近似名称。
+      for (const name of themeTokenNames) {
+        if (tokens[name]) continue;
+        const semanticNames = [name, ...(themeTokenAliases[name] ?? [])];
+        const candidates = semanticNames.flatMap((candidate) => candidate.startsWith("--color-")
+          ? [candidate, candidate.replace("--color-", "--app-color-")]
+          : [candidate]);
+        const value = candidates.map((candidate) => style.getPropertyValue(candidate).trim()).find(Boolean);
+        if (value) tokens[name] = value;
+      }
+      for (const [nativeName,internalName] of Object.entries(themeBindings)) {
+        if (!previousThemeBindings.has(internalName)) previousThemeBindings.set(internalName,root.style.getPropertyValue(internalName));
+        if (tokens[nativeName]) {tokens[internalName]=tokens[nativeName];if(root.style.getPropertyValue(internalName)!==tokens[nativeName]) root.style.setProperty(internalName,tokens[nativeName]);}
+        else if(root.style.getPropertyValue(internalName)) root.style.removeProperty(internalName);
+      }
+      const mode = root.dataset.theme === "dark" || root.classList.contains("electron-dark") || style.colorScheme === "dark"
+        ? "dark"
+        : "light";
+      return { root, style, tokens, mode };
+    }
+
+  function dispose() {for (const [name,value] of previousThemeBindings) { if(value) document.documentElement.style.setProperty(name,value); else document.documentElement.style.removeProperty(name); } }
+  return {read,dispose};
+}