weifuwu 0.50.0 → 0.51.0

package/README.md

@@ -16,7 +16,7 @@ npm install weifuwu
 
 **两阶段组件模型** — 组件 = `(initProps, ctx) => (props) => VNode`。外层函数只执行一次（mount），内层函数每次状态/props 变化时执行（render）。无 class、无 `this`、无 Hook。
 
-**Proxy 驱动渲染** — `ctx.ui.$()` 返回深度 Proxy，`$.x = val` 自动触发 VDOM patch。无需手动调用 `useState`/`useEffect`。
+**Proxy 驱动渲染** — `ctx.ui.$()` 返回深度 Proxy，`$.x = val` 自动触发当前组件的 VDOM patch。也支持手动 `ctx.ui.render()` 精确控制渲染时机。无需手动调用 `useState`/`useEffect`。
 
 **中间件注入一切** — 后端和前端共用同一理念：中间件向 `ctx` 注入能力（`ctx.sql` / `ctx.redis` / `ctx.api` / `ctx.auth` / `ctx.i18n` 等），Handler/组件从 `ctx` 读取。
 
@@ -116,7 +116,7 @@ createApp()
 |------|------|------|
 | 注入 | 中间件注入 ctx.field | 中间件注入 ctx.field |
 | 读取 | handler 读取 ctx | 组件读取 ctx |
-| 渲染 | 返回 Response | `ctx.ui.render()` / `ctx.ui.dirty()` 触发 VDOM patch |
+| 渲染 | 返回 Response | `ctx.ui.render()` / `ctx.ui.dirty()` / `$.x = val` 触发局部 VDOM patch |
 
 ### Closeable 接口
 
@@ -812,11 +812,14 @@ h('div', { class: 'x' }, child1, child2)
 
 ### Render 机制总览
 
-| API | 触发时机 | 渲染方式 | 使用场景 |
-|------|---------|---------|---------|
-| `$.x = val` | 赋值后自动 | 微任务批量（异步） | **日常 UI 状态** — 表单输入、切换开关、异步数据加载等绝大多数场景 |
-| `ctx.ui.dirty()` | 主动调用 | 微任务批量（异步） | **绕过 Proxy 后手动标记** — 批量修改深层次对象、第三方库直接修改了 `$` 内部数据 |
-| `ctx.ui.render()` | 主动调用 | 立即同步 | **需要立即拿到最新 DOM** — DOM 测量、动画触发、第三方库在事件中同步读取 DOM |
+| API | 触发时机 | 渲染方式 | 作用域 | 使用场景 |
+|------|---------|---------|--------|---------|
+| `$.x = val` | 赋值后自动 | 微任务批量（异步） | 当前组件 | **日常 UI 状态** — 表单输入、切换开关、异步数据加载等 |
+| `ctx.ui.dirty()` | 主动调用 | 微任务批量（异步） | 当前/指定 | **绕过 Proxy 后手动标记** |
+| `ctx.ui.render()` | 主动调用 | 立即同步 | 当前/指定 | **需要立即拿到最新 DOM** — DOM 测量、动画触发 |
+| `ctx.ui.render(['id'])` | 主动调用 | 立即同步 | 指定组件 | **跨组件精准刷新** — 全局事件、Portal 远程控制 |
+
+`render()` 和 `dirty()` 无参 = 当前组件，传参 = 指定组件列表。三套 API 同一 scope 机制。
 
 ### 闭包变量 + `ctx.ui.render()`（简单场景）
 
@@ -862,23 +865,13 @@ const FormPage: Component = (_init, ctx) => {
 - 不需要触发渲染的内部缓存（用闭包变量 `let`）
 - 简单组件只有一两个状态变量（闭包变量 + `render()` 更轻量）
 
-### `ctx.ui.dirty()` — 手动标记脏状态
-
-当你绕过 Proxy 直接操作底层数据后，调用 `dirty()` 通知框架在下个微任务批量重渲染：
-
-```tsx
-// 实际场景：在 mount 阶段需要手动触发渲染
-// mount 期间 $.x = val 自动静默（不触发渲染）
-$.initialized = true
-// 如果非要在这里触发渲染，需要手动调用 dirty()：
-ctx.ui.dirty()
-```
+### `ctx.ui.dirty()` — 异步标记脏
 
-**但实际上，绝大多数情况下你不需要 `dirty()`。** 深度 Proxy 已经拦截了所有常见的变更新为方式（深层属性赋值、数组 push/splice、delete 等）。先赋值给 `$` 永远是更清晰的做法。
+异步版本，无参 = 当前组件，传参 = 指定组件列表。多次调用合并为一次微任务渲染。`$` 内部就是调 `dirty()`。
 
 ### `ctx.ui.render()` — 同步强制渲染
 
-与 `dirty()` 的微任务批量不同，`render()` 是**同步执行**的。调用后立即执行 VDOM diff + patch，DOM 立刻更新。
+与 `dirty()` 的微任务批量不同，`render()` 是**同步执行**的。调用后立即执行 VDOM diff + patch，DOM 立刻更新。无参时只刷新当前组件，传参时可精准刷新指定组件。
 
 **何时必须用 `render()`**：
 
@@ -913,55 +906,57 @@ onClick: () => {
 ### 三种方式速查
 
 ```tsx
-// ✅ 推荐：ctx.ui.$() + $.x = val — 自动、批量、无脑
+// 自动：$.x = val — 微任务批量，绑定当前组件
 const $ = ctx.ui.$()
 $.count++
-$.name = 'hello'         // 微任务合并，只渲染一次
+$.name = 'hello'         // 多次赋值合并为一次渲染
 
-// ✅ 简单场景：闭包变量 + ctx.ui.render() — 轻量同步
+// 手动：ctx.ui.render() — 同步，无参=当前，传参=指定
 let count = 0
 count++
 ctx.ui.render()          // DOM 立刻更新
+ctx.ui.render(['stats']) // 精准刷新指定组件
 
-// ⚠️ 罕见：ctx.ui.dirty() — 绕过 Proxy 后手动标记
+// 异步：ctx.ui.dirty() — 微任务批量，同 render() 作用域
+ctx.ui.dirty()
+ctx.ui.dirty(['stats'])  // 批处理合并
 ```
 
 **性能说明**：
-- `$.x = val` 和 `dirty()` 都是微任务批量合并：同一 tick 内 N 次赋值 → 1 次渲染
-- `render()` 每次调用都触发一次完整 diff/patch，频繁调用可能影响性能
+- `$.x = val` 和 `dirty()` 都是微任务批量合并
+- `render()` 每次调用都触发一次完整 diff/patch
+- 三个入口同一套 scope 机制，不想要的渲染不触发
 
-### 实践建议：日常开发 vs 组件分享
+### 实践建议
 
-**日常组件内**：优先用 `$.x = val`，无脑、自动、批量。
+**组件库**（可分享组件）推荐手动模式：
 
-**制作可分享组件**（组件库、npm 包、跨项目复用）时，推荐用 `ctx.ui.dirty()` 或 `ctx.ui.render()` 精确控制刷新时机：
+```tsx
+const DatePicker = (_init, ctx) => {
+  let show = false             // let 不触发渲染
+  return (props) =>
+    h('input', {
+      onClick: () => { show = true; ctx.ui.render() }
+    })
+}
+```
+
+行为只由 `render()` 显式控制，不依赖 `$`，测试中 `render()` 直接 mock 为空函数。
+
+**业务层**推荐自动模式：
 
 ```tsx
-// 可分享的 Toast 组件：主动控制渲染，避免消费方上下文干扰
-const Toast = (_init, ctx) => {
-  let items: ToastItem[] = []
-
-  return {
-    add(item: ToastItem) {
-      items = [...items, item]
-      ctx.ui.render()       // 显式同步渲染，确保 DOM 立即可见
-    },
-    remove(id: string) {
-      items = items.filter(i => i.id !== id)
-      ctx.ui.dirty()        // 显式标记脏，下个微任务批量渲染
-    },
-    render: (props) =>
-      h('div', { class: 'toast-container' },
-        items.map(item => h('div', { key: item.id }, item.msg))
-      ),
-  }
+const OrderPage = (_init, ctx) => {
+  const $ = ctx.ui.$
+  $.orders = []                // $ 赋值自动触发渲染
+  $.loading = false
+  return (props) => h('div', {}, $.loading ? h(Spinner) : h(OrderList, { orders: $.orders }))
 }
 ```
 
-理由：
-- 分享出去的组件可能被用在各种上下文，`$` 的隐式自动刷新可能不可控
-- 暴露 `add/remove` 等命令式 API 时，`render()` / `dirty()` 让刷新时机**显式、可预测**
-- 消费方不需要知道组件内部用 `$` 还是闭包，只需调用 API
+省事、安全、`$` 绑定所属组件不波及兄弟。
+
+同一个组件内可以按变量混用两种模式：需要渲染的用 `$`，不需要的用 `let`。
 
 ---
 
@@ -1282,7 +1277,7 @@ createApp()
 
 // 运行时切换语言
 ctx.i18n?.setLocale('en-US')
-// → 自动触发全应用重渲染
+// → 自动触发根组件重渲染（所有组件使用新语言文案）
 ```
 
 | I18nOptions | 类型 | 默认值 | 说明 |
@@ -1574,6 +1569,9 @@ props 变化 ──────────────────────
 | `onmounted` | `ref` 的 `if (el)` 分支 |
 | `onunmount` | `ref` 的 `else` 分支 |
 | `onupdate` | render 内层函数收新 props 自行比较 |
+| `全局刷新` | `ctx.ui.render(['_wf_root'])` |
+| `局部刷新` | `ctx.ui.render()` 或 `$.x = val` |
+| `跨组件刷新` | `ctx.ui.selfId('name')` + `render(['name'])` |
 
 ## 组件列表
 

package/dist/client/app.d.ts

@@ -4,9 +4,15 @@
  * createApp() → app.use(mw) → app.mount('#root', RootComponent)
  *
  * ctx.ui 在 mount 时注入：
- *   ctx.ui.render()    触发组件重渲染
- *   ctx.ui.dirty()     标记脏状态，下个微任务批量渲染
- *   ctx.ui.$()         创建响应式状态容器（$.x = val 自动 dirty）
+ *   ctx.ui.render()        同步刷新当前组件
+ *   ctx.ui.render(['#id']) 同步刷新指定组件
+ *   ctx.ui.dirty()         异步刷新当前组件（微任务批处理）
+ *   ctx.ui.$()             响应式状态容器（$.x = val 自动 dirty）
+ *
+ * render / dirty / $ 通过 prototype chain 实现组件级 scope：
+ *   每个组件 mount 时创建 childCtx.ui = Object.create(ctx.ui)
+ *   并设置 childCtx.ui._selfId = 组件 ID
+ *   render() 无参时从 this._selfId 取当前组件 ID
  */
 import type { WfuiContext, AppMiddleware } from './types.ts';
 import type { Component } from './vnode.ts';

package/dist/client/index.js

@@ -39,6 +39,8 @@ function createPortal(children, portalKey) {
 // src/client/render.ts
 var SVG_NS = "http://www.w3.org/2000/svg";
 var SVG_TAGS = /* @__PURE__ */ new Set(["svg", "path", "circle", "line", "rect", "text", "g", "polyline", "polygon", "ellipse", "defs", "use", "clipPath", "mask", "linearGradient", "radialGradient", "stop", "tspan"]);
+var _idCounter = 0;
+var idRegistry = /* @__PURE__ */ new Map();
 function render(input, ctx) {
   return renderValue(input, ctx);
 }
@@ -76,7 +78,15 @@ function renderValue(v, ctx) {
   } else {
     const flatChildren = flattenChildren(vnode.props?.children);
     for (const child of flatChildren) {
-      el.appendChild(renderValue(child, ctx));
+      const childNode = renderValue(child, ctx);
+      el.appendChild(childNode);
+      if (child && typeof child === "object" && typeof child.type === "function") {
+        const childVNode = child;
+        if (!childVNode._parentNode) {
+          childVNode._parentNode = el;
+          childVNode._refNode = childNode;
+        }
+      }
     }
   }
   if (selectValue !== void 0) {
@@ -89,9 +99,17 @@ function renderValue(v, ctx) {
 function renderComponent(Comp, props, vnode, ctx) {
   ;
   ctx.ui = ctx.ui ?? {};
+  if (!vnode._id) {
+    vnode._id = `_wf_${_idCounter++}`;
+    idRegistry.set(vnode._id, vnode);
+  }
+  const childCtx = Object.create(ctx);
+  childCtx.ui = Object.create(ctx.ui);
+  childCtx.ui._selfId = vnode._id;
+  childCtx.ui._selfVNode = vnode;
   let childVNode;
   try {
-    childVNode = Comp(props, ctx);
+    childVNode = Comp(props, childCtx);
     if (typeof childVNode !== "function") {
       throw new Error(
         `Component ${Comp.name || "anonymous"} must return a render function. Use (init_props, ctx) => (props) => VNode pattern.`
@@ -236,14 +254,23 @@ function patchValue(parent, oldNode, oldInput, newInput, ctx) {
   const oldV = oldInput;
   if (typeof newV.type === "function") {
     const comp = newV.type;
-    ctx.ui = ctx.ui ?? {};
-    if (oldV._render) newV._render = oldV._render;
+    if (oldV._render) {
+      newV._render = oldV._render;
+      newV._id = oldV._id;
+      if (newV._id) idRegistry.set(newV._id, newV);
+    }
+    newV._parentNode = parent;
+    newV._refNode = oldNode;
+    const childCtx = Object.create(ctx);
+    childCtx.ui = Object.create(ctx.ui);
+    childCtx.ui._selfId = newV._id;
+    childCtx.ui._selfVNode = newV;
     let childNew;
     try {
       if (typeof newV._render === "function") {
         childNew = newV._render(newV.props);
       } else {
-        childNew = comp(newV.props, ctx);
+        childNew = comp(newV.props, childCtx);
         if (typeof childNew === "function") {
           newV._render = childNew;
           childNew = childNew(newV.props);
@@ -618,7 +645,49 @@ function createApp() {
   let container = null;
   let rootComponent = null;
   let oldVNode = null;
-  let rendered = false;
+  let _rendering = false;
+  let _dirtyBatch = /* @__PURE__ */ new Set();
+  let _dirtyScheduled = false;
+  function renderByIds(ids) {
+    if (_rendering) return;
+    _rendering = true;
+    layoutDepth.delete(ctx);
+    for (const id of ids) {
+      const vnode = idRegistry.get(id);
+      if (!vnode || !vnode._render) continue;
+      const oldChild = vnode._child;
+      const newChild = vnode._render(vnode.props);
+      vnode._child = newChild;
+      if (vnode._parentNode) {
+        const newNode = patchValue(
+          vnode._parentNode,
+          vnode._refNode ?? null,
+          oldChild,
+          newChild,
+          ctx
+        );
+        if (newNode && newNode !== vnode._refNode) {
+          vnode._refNode = newNode;
+        }
+      }
+    }
+    _rendering = false;
+    flushDirtyBatch();
+  }
+  function flushDirtyBatch() {
+    if (_dirtyBatch.size > 0 && !_dirtyScheduled) {
+      _dirtyScheduled = true;
+      queueMicrotask(() => {
+        _dirtyScheduled = false;
+        const batch = [..._dirtyBatch];
+        _dirtyBatch.clear();
+        if (batch.length > 0) renderByIds(batch);
+      });
+    }
+  }
+  function getSelfId(uiObj) {
+    return uiObj?._selfId ?? ctx.ui?._selfId;
+  }
   const app = {
     get ctx() {
       return ctx;
@@ -636,43 +705,72 @@ function createApp() {
       if (!el) throw new Error(`mount target not found: ${rootSelector}`);
       container = el;
       container.innerHTML = "";
-      let _dirty = false;
-      let _rendering = false;
-      const doRender = () => {
-        if (_rendering || !container || !rootComponent || !oldVNode) return;
-        _rendering = true;
-        layoutDepth.delete(ctx);
-        const newVNode = wrapComponent(rootComponent, ctx);
-        const oldNode = container.firstChild;
-        if (oldNode) {
-          patchValue(container, oldNode, oldVNode, newVNode, ctx);
-        }
-        oldVNode = newVNode;
-        _rendering = false;
-      };
-      const scheduleRender = () => {
-        if (_dirty || _rendering) return;
-        _dirty = true;
-        queueMicrotask(() => {
-          if (!_dirty) return;
-          _dirty = false;
-          doRender();
-        });
-      };
       ctx.ui = {
-        /** 立即同步渲染 */
-        render: doRender,
-        /** 标记脏状态，下个微任务批量渲染 */
-        dirty: scheduleRender,
-        /** 创建响应式状态容器：$.x = val 自动触发 dirty()（仅事件/timer 中生效） */
-        $: () => createReactiveState(scheduleRender)
+        _selfId: "_wf_root",
+        /** 同步刷新（无参 = 当前组件，传参 = 指定组件列表） */
+        render: function(ids) {
+          if (!ids || ids.length === 0) {
+            const selfId = getSelfId(this);
+            if (selfId) ids = [selfId];
+            else return;
+          }
+          renderByIds(ids);
+        },
+        /** 异步刷新（微任务批处理，无参 = 当前组件） */
+        dirty: function(ids) {
+          if (_rendering) return;
+          if (!ids || ids.length === 0) {
+            const selfId = getSelfId(this);
+            if (selfId) ids = [selfId];
+            else return;
+          }
+          for (const id of ids) {
+            if (id) _dirtyBatch.add(id);
+          }
+          if (!_dirtyScheduled) {
+            _dirtyScheduled = true;
+            queueMicrotask(() => {
+              _dirtyScheduled = false;
+              const batch = [..._dirtyBatch];
+              _dirtyBatch.clear();
+              if (batch.length > 0) renderByIds(batch);
+            });
+          }
+        },
+        /** 创建响应式状态容器：$.x = val 自动触发 dirty() */
+        $: function() {
+          const selfId = getSelfId(this);
+          return createReactiveState(() => {
+            if (selfId) ctx.ui.dirty([selfId]);
+          });
+        },
+        /** 注册组件实例的自定义 ID（用于跨组件精准刷新） */
+        selfId: function(name) {
+          if (typeof name !== "string" || !name) {
+            throw new Error(`[weifuwu] selfId requires a non-empty string, got ${typeof name}`);
+          }
+          if (idRegistry.has(name)) {
+            throw new Error(
+              `[weifuwu] Duplicate component ID: "${name}". Each component must have a unique custom ID.`
+            );
+          }
+          const vnode = this._selfVNode;
+          if (!vnode) return;
+          vnode._customId = name;
+          idRegistry.set(name, vnode);
+        }
       };
       _rendering = true;
       oldVNode = wrapComponent(RootComponent, ctx);
+      oldVNode._id = "_wf_root";
+      oldVNode._parentNode = container;
+      oldVNode._refNode = null;
+      idRegistry.set("_wf_root", oldVNode);
       const node = render(oldVNode, ctx);
       if (node instanceof Node) container.appendChild(node);
+      oldVNode._refNode = container.firstChild;
       _rendering = false;
-      rendered = true;
+      flushDirtyBatch();
     },
     destroy() {
       if (container) container.innerHTML = "";

package/dist/client/render.d.ts

@@ -12,6 +12,7 @@
  */
 import type { VNode } from './vnode.ts';
 import type { WfuiContext } from './types.ts';
+export declare const idRegistry: Map<string, VNode>;
 export declare function render(input: any, ctx: WfuiContext): Node;
 export declare function patchValue(parent: Node, oldNode: Node | null, oldInput: any, newInput: any, ctx: WfuiContext): Node | null;
 export declare function mountVNode(container: Element, vnode: VNode, ctx: WfuiContext): void;

package/dist/client/types.d.ts

@@ -6,12 +6,18 @@ export interface WfuiContext {
     [key: string]: unknown;
     /** UI 框架能力（由 createApp.mount 注入） */
     ui: {
-        /** 触发组件重渲染 */
-        render: () => void;
-        /** 标记脏状态，下一个微任务批量渲染 */
-        dirty: () => void;
-        /** 创建响应式状态容器：$.x = val 自动触发 dirty()（微任务批量渲染） */
+        /** 触发组件重渲染（同步，无参 = 当前组件） */
+        render: (ids?: string[]) => void;
+        /** 异步触发组件重渲染（微任务批处理，无参 = 当前组件） */
+        dirty: (ids?: string[]) => void;
+        /** 创建响应式状态容器：$.x = val 自动触发 dirty() */
         $: () => Record<string, any>;
+        /** 注册组件实例的自定义语义 ID，同名冲突抛错 */
+        selfId: (name: string) => void;
+        /** 当前组件实例 ID（仅供内部使用，通过 ctx 扩展注入） */
+        _selfId?: string;
+        /** 当前组件 VNode 引用（仅供内部使用，通过 ctx 扩展注入） */
+        _selfVNode?: any;
     };
     /** 路由（由 router 中间件注入） */
     route?: {

package/dist/client/vnode.d.ts

@@ -19,6 +19,12 @@ export interface VNode {
     _portalEl?: HTMLDivElement | undefined;
     /** 两阶段组件的 render 函数（mount 返回的函数） */
     _render?: (props: any) => VNode | null;
+    /** 组件实例 ID（如 '_wf_0'） */
+    _id?: string;
+    /** 组件输出的 DOM 父节点 */
+    _parentNode?: Node;
+    /** 组件输出的第一个 DOM 节点 */
+    _refNode?: Node | null;
 }
 export type Component<P = {}> = (initProps: P, ctx: WfuiContext) => ((props: P) => VNode | null) | null;
 export declare const Fragment: unique symbol;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "weifuwu",
   "type": "module",
-  "version": "0.50.0",
+  "version": "0.51.0",
   "description": "AI SaaS framework — (req, ctx) => Response",
   "exports": {
     ".": {