miaoda-expo-devkit 0.1.1-beta.1 → 0.1.1-beta.11

package/README.md

@@ -263,5 +263,174 @@ sentry-react-native-stub.js
 |---|---|---|
 | `.` | `dist/index.js` | `SentryCapture`、`MetroSymbolicator`、全部类型 |
 | `./metro` | `dist/metro.js` | `withDevStubs`、`withEntryInjection` |
+| `./babel-plugin-jsx-source` | `dist/babel/plugin-jsx-source.js` | Babel 插件：为 JSX 注入 source 信息 |
 | `./sentry-react-native-stub` | `dist/stubs/sentry-react-native-stub.js` | `@sentry/react-native` 模块替换 stub |
 | `./no-op-logbox` | `dist/stubs/no-op-logbox.js` | LogBox no-op stub |
+
+---
+
+## Stubs 模块说明
+
+### entry-inject.js
+
+由 `expo-router-entry-stub.js` 在 `expo-router/entry-classic` 执行前 require，因此代码运行时机早于 expo-router 初始化和任何路由渲染。
+
+**功能：**
+- 设置全局标记 `globalThis.__DEVKIT_INJECTED__ = true`（供测试验证）
+- 安装 HMR postMessage 控制器
+- 安装 LGUI 可视化编辑器控制器
+- 安装 CSS 注入控制器
+- 安装路由消息控制器
+
+---
+
+### expo-router-entry-stub.js
+
+Metro 的 `resolveRequest` 将 `expo-router/entry-classic` 重定向到此文件。
+
+**执行顺序：**
+1. entry-inject（注入脚本）
+2. expo-router/entry-classic（原 expo-router 入口，负责注册 App）
+
+---
+
+### hmr-control.js
+
+HMR postMessage 控制器，监听 window 上的 postMessage 消息来控制 HMR。
+
+**消息格式：**
+```ts
+window.postMessage({ type: 'devkit:hmr', action: 'enable' | 'disable' }, '*')
+```
+
+**副作用：**
+- 设置 `globalThis.__DEVKIT_HMR_ENABLED__`（初始值 true），随每条消息更新
+- 在 `__DEV__` 模式下调用 `expo/src/async-require/hmr` 的 `enable()` / `disable()`，实际暂停或恢复 Fast Refresh
+
+---
+
+### css-control.js
+
+CSS 注入控制器，为 LGUI 编辑器提供可视化高亮样式。
+
+**高亮属性：**
+- `data-editor-active`：选中元素（2px 实线边框）
+- `data-editor-hover`：悬停元素（1px 实线边框）
+- `data-editor-each`：同源兄弟元素（1px 虚线边框）
+- `data-editor-full-width`：全宽元素（使用内缩 offset）
+
+**导出函数：**
+- `injectSelectorModeStyle()`：注入选择模式样式，返回移除函数
+- `setupCSSInjectionControl()`：注入编辑器高亮 CSS（页面加载时注入，常驻）
+
+---
+
+### lgui-control.js
+
+LGUI 可视化编辑器 postMessage 控制器，实现可视化编辑器与 iframe 内页面的双向通信。
+
+**消息格式（父窗口 → iframe）：**
+```ts
+window.postMessage({ type: 'editor-inject' }, '*')    // 初始化编辑器
+window.postMessage({ type: 'editor-destroy' }, '*')   // 销毁编辑器
+```
+
+**消息格式（iframe → 父窗口）：**
+```ts
+parent.postMessage({ type: 'iframe-target-change', target: ElementInfo }, '*')
+parent.postMessage({ type: 'iframe-scroll', target: Rect }, '*')
+```
+
+**功能：**
+- 监听鼠标事件（mouseover、mouseleave、click），处理 hover/active 状态
+- 与父窗口通信，发送选中元素信息（位置、组件名、源码位置等）
+- 观察选中节点属性变化，实时同步信息
+- 高亮同源兄弟节点
+
+---
+
+### router-control.js
+
+LGUI 路由控制器，监听父窗口 postMessage 处理路由导航和页面刷新。
+
+**消息格式（父窗口 → iframe）：**
+```ts
+window.postMessage({ type: 'editor-location-update', pageName: string }, '*')  // 更新路由
+window.postMessage({ type: 'editor-refresh' }, '*')                          // 刷新页面
+```
+
+**功能：**
+- `editor-location-update`：更新路由（使用 `history.pushState`）
+- `editor-refresh`：刷新页面（使用 `location.reload`）
+
+---
+
+### sentry-react-native-stub.js
+
+`@sentry/react-native` 模块替换 stub，由 `withDevStubs()` 在 Metro 层自动注入。
+
+**功能：**
+- 将用户传入的 DSN 替换为无害的覆盖值（默认 `https://stubPublicKey@o0.ingest.sentry.io/0`）
+- 自动注入内置 SentryCapture，监听并符号化 Sentry 错误事件
+- 串联调用方传入的 `beforeSend` / `beforeBreadcrumb`（内置捕获器先执行）
+- 向父窗口发送 `GLOBAL_ERROR` 事件，携带错误信息
+
+**环境变量：**
+- `SENTRY_OVERRIDE_DSN`：自定义覆盖 DSN（如指向本地 relay）
+
+---
+
+### no-op-logbox.js
+
+LogBox no-op stub，用于 web 平台禁用 Expo 全屏错误遮罩。
+
+由 `withDevStubs()` 在 Metro 层将 `@expo/log-box` 和 `ErrorOverlayWebControls` 重定向到此文件。
+
+---
+
+## Babel 插件：jsx-source
+
+`babel-plugin-jsx-source` 为 JSX 元素注入 source 属性（文件路径、行列号），用于开发调试。通过 `dataSet` 对象注入，这是 React Web 可识别的数据通道。
+
+### 配置
+
+```js
+// babel.config.js
+module.exports = {
+  plugins: [
+    ['miaoda-expo-devkit/babel-plugin-jsx-source', { rootDir: __dirname }]
+  ]
+};
+```
+
+### 转换效果
+
+普通 JSX 元素：
+```tsx
+// 转换前
+<View style={styles.container} />
+
+// 转换后
+<View style={styles.container} dataSet={{"mdId": "path/to/file.tsx:10:4"}} />
+```
+
+纯文本节点（会添加 `componentContent`，使用 URL 编码格式）：
+```tsx
+// 转换前
+<div>hello world</div>
+
+// 转换后
+<div dataSet={{"mdId": "path/to/file.tsx:10:4", "componentContent": "%7B%22text%22%3A%22hello%20world%22%7D"}}>hello world</div>
+```
+
+`componentContent` 解码后为：
+```json
+{"text":"hello world"}
+```
+
+### 选项
+
+| 选项 | 类型 | 默认值 | 说明 |
+|---|---|---|---|
+| `rootDir` | `string` | - | 项目根目录，用于计算相对路径。不提供则使用绝对路径 |
+| `excludePaths` | `string[]` | `[]` | 跳过注入的路径模式列表（相对于 rootDir 的路径片段） |

package/biome-config.json

@@ -0,0 +1,14 @@
+{
+	"linter": {
+		"enabled": true,
+		"rules": {
+			"recommended": false,
+			"correctness": {
+				"noUndeclaredDependencies": "error"
+			}
+		}
+	},
+	"formatter": {
+		"enabled": false
+	}
+}

package/dist/babel/plugin-jsx-source.d.ts

@@ -0,0 +1,48 @@
+import { types, PluginObj } from '@babel/core';
+
+/**
+ * babel-plugin-jsx-source
+ *
+ * 为 JSX 元素注入 source 属性，包含文件路径、行列号信息，用于开发调试。
+ * 通过 dataSet 对象注入，这是 React Web 可识别的数据通道。
+ *
+ * 转换前：
+ *   <View style={styles.container} />
+ *
+ * 转换后：
+ *   <View style={styles.container} dataSet={{"mdId": "path/to/file.tsx:10:4"}} />
+ *
+ * 对于纯文本节点：
+ *   <div>hello world</div>
+ *   <div>{"hello world"}</div>
+ * 转换后：
+ *   <div dataSet={{"mdId": "path/to/file.tsx:10:4", "componentContent": "{\"text\":\"hello world\"}"}}>hello world</div>
+ *   <div dataSet={{"mdId": "path/to/file.tsx:11:4", "componentContent": "{\"text\":\"hello world\"}"}}>{"hello world"}</div>
+ *
+ * 用法（babel.config.js）：
+ *
+ *   module.exports = {
+ *     plugins: [
+ *       ['miaoda-expo-devkit/babel-plugin-jsx-source', { rootDir: __dirname }]
+ *     ]
+ *   };
+ *
+ * 选项：
+ *   - rootDir: 项目根目录，用于计算相对路径（可选，默认使用绝对路径）
+ */
+
+/** 插件选项 */
+interface JsxSourcePluginOptions {
+    /** 项目根目录，用于计算相对路径。若不提供则使用绝对路径 */
+    rootDir?: string;
+    /** 需要跳过注入的路径模式列表（相对于 rootDir 的路径片段） */
+    excludePaths?: string[];
+}
+/**
+ * Babel 插件：为 JSX 元素注入 dataSet
+ */
+declare function babelPluginJsxSource({ types: t, }: {
+    types: typeof types;
+}): PluginObj;
+
+export { type JsxSourcePluginOptions, babelPluginJsxSource as default };

package/dist/babel/plugin-jsx-source.js

@@ -23,20 +23,65 @@ __export(plugin_jsx_source_exports, {
   default: () => babelPluginJsxSource
 });
 module.exports = __toCommonJS(plugin_jsx_source_exports);
-function createSourceObject(t, fileName, lineNumber, columnNumber) {
-  return t.objectExpression([
-    t.objectProperty(t.identifier("fileName"), t.stringLiteral(fileName)),
-    t.objectProperty(t.identifier("lineNumber"), t.numericLiteral(lineNumber)),
-    t.objectProperty(t.identifier("columnNumber"), t.numericLiteral(columnNumber))
-  ]);
+var DATASET_PROP_NAME = "dataSet";
+var MD_ID_KEY = "mdId";
+var MD_CONTENT_KEY = "componentContent";
+var REACT_SPECIAL_COMPONENTS = /* @__PURE__ */ new Set([
+  "Fragment",
+  "Suspense",
+  "StrictMode",
+  "Profiler"
+]);
+function findDataSetAttr(t, attributes) {
+  return attributes.find(
+    (attr) => t.isJSXAttribute(attr) && t.isJSXIdentifier(attr.name, { name: DATASET_PROP_NAME })
+  );
+}
+function getMdIdFromDataSet(t, obj) {
+  for (const p of obj.properties) {
+    if (t.isObjectProperty(p) && t.isIdentifier(p.key) && p.key.name === MD_ID_KEY && t.isStringLiteral(p.value)) {
+      return p.value.value;
+    }
+  }
+  return null;
+}
+function getComponentContentFromDataSet(t, obj) {
+  for (const p of obj.properties) {
+    if (t.isObjectProperty(p) && t.isIdentifier(p.key) && p.key.name === MD_CONTENT_KEY && t.isStringLiteral(p.value)) {
+      return p.value.value;
+    }
+  }
+  return null;
+}
+function removeMdIdFromDataSet(t, obj) {
+  obj.properties = obj.properties.filter(
+    (p) => !(t.isObjectProperty(p) && t.isIdentifier(p.key) && p.key.name === MD_ID_KEY)
+  );
 }
-function hasSourceAttribute(t, attributes) {
-  return attributes.some(
-    (attr) => t.isJSXAttribute(attr) && t.isJSXIdentifier(attr.name, { name: SOURCE_PROP_NAME })
+function removeComponentContentFromDataSet(t, obj) {
+  obj.properties = obj.properties.filter(
+    (p) => !(t.isObjectProperty(p) && t.isIdentifier(p.key) && p.key.name === MD_CONTENT_KEY)
   );
 }
-var SOURCE_PROP_NAME = "__jsxsource";
-var REACT_SPECIAL_COMPONENTS = /* @__PURE__ */ new Set(["Fragment", "Suspense", "StrictMode", "Profiler"]);
+function getTextNodeContent(t, path) {
+  const parent = path.parent;
+  if (!t.isJSXElement(parent)) return null;
+  const children = parent.children;
+  if (children.length !== 1) return null;
+  const child = children[0];
+  if (t.isJSXText(child)) {
+    const text = child.value.trim();
+    return text || null;
+  }
+  if (t.isJSXExpressionContainer(child) && t.isStringLiteral(child.expression)) {
+    const text = child.expression.value.trim();
+    return text || null;
+  }
+  if (t.isJSXExpressionContainer(child) && t.isNumericLiteral(child.expression)) {
+    return String(child.expression.value);
+  }
+  return null;
+}
 function shouldSkipElement(t, name) {
   if (t.isJSXIdentifier(name)) {
     return REACT_SPECIAL_COMPONENTS.has(name.name);
@@ -67,23 +112,68 @@ function babelPluginJsxSource({
         if (filename.includes("node_modules")) return;
         if (opts.excludePaths?.some((p) => filename.includes(p))) return;
         if (shouldSkipElement(t, path.node.name)) return;
-        if (hasSourceAttribute(t, path.node.attributes)) return;
         const loc = path.node.loc;
         if (!loc) return;
         let filePath = filename;
         if (opts.rootDir && filename.startsWith(opts.rootDir)) {
           filePath = filename.slice(opts.rootDir.length);
-          if (filePath.startsWith("/")) {
-            filePath = filePath.slice(1);
+          if (filePath.startsWith("/")) filePath = filePath.slice(1);
+        }
+        const value = `${filePath}:${loc.start.line}:${loc.start.column}`;
+        const attrs = path.node.attributes;
+        const existing = findDataSetAttr(t, attrs);
+        if (existing) {
+          if (t.isJSXExpressionContainer(existing.value) && t.isObjectExpression(existing.value.expression)) {
+            const obj = existing.value.expression;
+            const oldMdId = getMdIdFromDataSet(t, obj);
+            if (oldMdId !== value) {
+              removeMdIdFromDataSet(t, obj);
+              obj.properties.push(
+                t.objectProperty(
+                  t.identifier(MD_ID_KEY),
+                  t.stringLiteral(value)
+                )
+              );
+            }
+            const textContent2 = getTextNodeContent(t, path);
+            const newComponentContent = textContent2 ? encodeURIComponent(JSON.stringify({ text: textContent2 })) : null;
+            const oldComponentContent = getComponentContentFromDataSet(t, obj);
+            if (oldComponentContent !== newComponentContent) {
+              removeComponentContentFromDataSet(t, obj);
+              if (newComponentContent) {
+                obj.properties.push(
+                  t.objectProperty(
+                    t.identifier(MD_CONTENT_KEY),
+                    t.stringLiteral(newComponentContent)
+                  )
+                );
+              }
+            }
           }
+          return;
+        }
+        const properties = [
+          t.objectProperty(
+            t.identifier(MD_ID_KEY),
+            t.stringLiteral(value)
+          )
+        ];
+        const textContent = getTextNodeContent(t, path);
+        if (textContent) {
+          properties.push(
+            t.objectProperty(
+              t.identifier(MD_CONTENT_KEY),
+              t.stringLiteral(encodeURIComponent(JSON.stringify({ text: textContent })))
+            )
+          );
         }
-        const sourceAttribute = t.jsxAttribute(
-          t.jsxIdentifier(SOURCE_PROP_NAME),
+        const attr = t.jsxAttribute(
+          t.jsxIdentifier(DATASET_PROP_NAME),
           t.jsxExpressionContainer(
-            createSourceObject(t, filePath, loc.start.line, loc.start.column)
+            t.objectExpression(properties)
           )
         );
-        path.node.attributes.push(sourceAttribute);
+        attrs.push(attr);
       }
     }
   };

package/dist/babel/preset.d.ts

@@ -0,0 +1,24 @@
+import { ConfigAPI, TransformOptions } from '@babel/core';
+
+/**
+ * babel-preset-expo-devkit
+ *
+ * 封装 Expo + NativeWind 标准 babel 配置，供基于本模板的项目直接引用。
+ * 升级 devkit 版本即可获得最新配置，无需手动维护 babel.config.js。
+ */
+
+interface PresetOptions {
+    /**
+     * 项目根目录，用于 babel-plugin-jsx-source 计算相对路径。
+     * 默认为 process.cwd()（Babel 始终从项目根运行）。
+     */
+    rootDir?: string;
+    /**
+     * 需要跳过 jsx-source 注入的路径前缀列表（相对于 rootDir）。
+     * 例如：['src/components/ui']
+     */
+    excludePaths?: string[];
+}
+declare function presetExpoDevkit(api: ConfigAPI, options?: PresetOptions): TransformOptions;
+
+export { presetExpoDevkit as default };

package/dist/babel/preset.js

@@ -0,0 +1,50 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/babel/preset.ts
+var preset_exports = {};
+__export(preset_exports, {
+  default: () => presetExpoDevkit
+});
+module.exports = __toCommonJS(preset_exports);
+function presetExpoDevkit(api, options = {}) {
+  const isDev = api.env("development");
+  const { rootDir = process.cwd(), excludePaths = [] } = options;
+  return {
+    presets: [
+      ["babel-preset-expo", { jsxImportSource: "nativewind" }],
+      "nativewind/babel"
+    ],
+    plugins: isDev ? [
+      // require.resolve 确保引用绝对路径，避免 Babel 解析歧义
+      [require.resolve("./plugin-jsx-source"), { rootDir, excludePaths }]
+    ] : []
+  };
+}
+//# sourceMappingURL=preset.js.map

package/dist/cli/lint.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+"use strict";
+
+// src/cli/lint.ts
+var import_node_child_process = require("child_process");
+var import_node_path = require("path");
+var devkitRoot = (0, import_node_path.resolve)(__dirname, "../..");
+var oxlintConfig = (0, import_node_path.join)(devkitRoot, "oxlint-config.json");
+var biomeConfig = (0, import_node_path.join)(devkitRoot, "biome-config.json");
+var targets = process.argv.slice(2);
+var lintTargets = targets.length > 0 ? targets : ["src/"];
+var failed = false;
+var oxlint = (0, import_node_child_process.spawnSync)("oxlint", ["--config", oxlintConfig, ...lintTargets], {
+  stdio: "inherit"
+});
+if ((oxlint.status ?? 1) !== 0) failed = true;
+var biome = (0, import_node_child_process.spawnSync)("biome", ["lint", "--config-path", biomeConfig, ...lintTargets], {
+  stdio: "inherit"
+});
+if ((biome.status ?? 1) !== 0) failed = true;
+process.exit(failed ? 1 : 0);