@pactor-app/runtime 1.54.4 → 1.55.0

package/dist/index.cjs

@@ -26,6 +26,7 @@ __export(index_exports, {
   DslSourceBoundary: () => DslSourceBoundary,
   DslSourceResolver: () => DslSourceResolver,
   I18nContextProvider: () => I18nContextProvider,
+  LocalizationProtocolError: () => LocalizationProtocolError,
   PageRuntimeError: () => PageRuntimeError,
   PageRuntimeView: () => PageRuntimeView,
   StateStore: () => StateStore,
@@ -109,13 +110,42 @@ function createFetchHttpAdapter() {
 }
 
 // src/context/context.ts
-var import_core = require("@pactor-app/core");
+var import_core2 = require("@pactor-app/core");
 
 // src/utils/resolve.ts
+var import_core = require("@pactor-app/core");
 var import_expression = require("@pactor-app/expression");
 function isPlainRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+var LocalizationProtocolError = class extends Error {
+  constructor(message) {
+    super(`[@pactor-app/runtime] ${message}`);
+    this.name = "LocalizationProtocolError";
+  }
+};
+function interpolateLocalizedText(template, params) {
+  return template.replace(/\{\{(\w+)\}\}/g, (match, name) => {
+    const value = params[name];
+    if (value === void 0 || value === null) {
+      console.warn(
+        `[@pactor-app/runtime] $localizedText \u672A\u77E5\u53C2\u6570 "${name}"\uFF0C\u4FDD\u7559\u5360\u4F4D\u7B26 ${match}`
+      );
+      return match;
+    }
+    return String(value);
+  });
+}
+function resolveLocalizedText(value, scope, options) {
+  const { template, params } = value.$localizedText;
+  const resolvedParams = {};
+  if (isPlainRecord(params)) {
+    for (const [key, item] of Object.entries(params)) {
+      resolvedParams[key] = resolveDeep(item, scope, options);
+    }
+  }
+  return interpolateLocalizedText(template, resolvedParams);
+}
 function resolveDeep(value, scope, options = {}) {
   if (typeof value === "string") {
     return (0, import_expression.hasExpression)(value) ? (0, import_expression.resolveTemplate)(value, scope) : value;
@@ -124,6 +154,14 @@ function resolveDeep(value, scope, options = {}) {
     return value.map((item) => resolveDeep(item, scope, options));
   }
   if (isPlainRecord(value)) {
+    if (options.localizationMode === "server" && (0, import_core.isI18nDescriptor)(value)) {
+      throw new LocalizationProtocolError(
+        "server \u672C\u5730\u5316\u6A21\u5F0F\u4E0B\u4F5C\u8005\u6001 `$i18n` \u4E0D\u5141\u8BB8\u51FA\u73B0\u5728\u5BA2\u6237\u7AEF\u89E3\u6790\u8DEF\u5F84"
+      );
+    }
+    if ((0, import_core.isLocalizedText)(value)) {
+      return resolveLocalizedText(value, scope, options);
+    }
     if (options.isOpaque?.(value)) {
       return value;
     }
@@ -149,6 +187,7 @@ var DataStore = class {
     this.services = deps.services;
     this.http = deps.http;
     this.getScope = deps.getScope;
+    this.localizationMode = deps.localizationMode;
     for (const name of Object.keys(deps.dataSources)) {
       this.statuses.set(name, { loading: false });
     }
@@ -282,7 +321,9 @@ var DataStore = class {
             `[@pactor-app/runtime] service not registered: "${serviceName}"`
           );
         }
-        const params = resolveDeep(config.params ?? {}, this.getScope());
+        const params = resolveDeep(config.params ?? {}, this.getScope(), {
+          localizationMode: this.localizationMode
+        });
         return handler(params);
       }
       case "http": {
@@ -291,7 +332,8 @@ var DataStore = class {
         }
         const request = resolveDeep(
           config.request,
-          this.getScope()
+          this.getScope(),
+          { localizationMode: this.localizationMode }
         );
         return this.http.request(request);
       }
@@ -336,13 +378,10 @@ function applyOptionMapping(data, config) {
 }
 
 // src/datasource/dsl-source-resolver.ts
-function dslSourceKey(ref) {
+function dslSourceKey(ref, locale) {
   const source = ref.source;
-  if (source.type === "service") {
-    return `service:${source.service}:${JSON.stringify(source.params ?? {})}`;
-  }
-  const request = source.request;
-  return `http:${(request.method ?? "GET").toUpperCase()}:${request.url}:${JSON.stringify(request.params ?? {})}:${JSON.stringify(request.headers ?? {})}`;
+  const base = source.type === "service" ? `service:${source.service}:${JSON.stringify(source.params ?? {})}` : `http:${(source.request.method ?? "GET").toUpperCase()}:${source.request.url}:${JSON.stringify(source.request.params ?? {})}:${JSON.stringify(source.request.headers ?? {})}`;
+  return locale ? `${locale}|${base}` : base;
 }
 var DslSourceResolver = class {
   constructor(deps) {
@@ -350,7 +389,7 @@ var DslSourceResolver = class {
     this.cache = /* @__PURE__ */ new Map();
   }
   resolve(ref) {
-    const key = dslSourceKey(ref);
+    const key = dslSourceKey(ref, this.deps.locale);
     let cached = this.cache.get(key);
     if (cached === void 0) {
       cached = this.load(ref);
@@ -360,6 +399,7 @@ var DslSourceResolver = class {
   }
   async load(ref) {
     const scope = this.deps.getScope();
+    const resolveOptions = { localizationMode: this.deps.localizationMode };
     const source = ref.source;
     if (source.type === "service") {
       const handler = this.deps.services.get(source.service);
@@ -368,10 +408,14 @@ var DslSourceResolver = class {
           `[@pactor-app/runtime] service not registered: "${source.service}"`
         );
       }
-      const params = resolveDeep(source.params ?? {}, scope);
+      const params = resolveDeep(source.params ?? {}, scope, resolveOptions);
       return handler(params);
     }
-    const request = resolveDeep(source.request, scope);
+    const request = resolveDeep(
+      source.request,
+      scope,
+      resolveOptions
+    );
     return this.deps.http.request(request);
   }
 };
@@ -474,11 +518,11 @@ function setPath(source, path, value) {
 // src/context/context.ts
 function createRuntimeContext(options = {}) {
   const state = new StateStore(options.state);
-  const services = options.services ?? new import_core.Registry("ServiceRegistry");
-  const components = options.components ?? new import_core.Registry("ComponentRegistry");
-  const actions = options.actions ?? new import_core.Registry("ActionRegistry");
-  const forms = options.forms ?? new import_core.Registry("FormRegistry");
-  const capabilities = options.capabilities ?? new import_core.Registry("CapabilityRegistry");
+  const services = options.services ?? new import_core2.Registry("ServiceRegistry");
+  const components = options.components ?? new import_core2.Registry("ComponentRegistry");
+  const actions = options.actions ?? new import_core2.Registry("ActionRegistry");
+  const forms = options.forms ?? new import_core2.Registry("FormRegistry");
+  const capabilities = options.capabilities ?? new import_core2.Registry("CapabilityRegistry");
   const permission = options.permission ?? createDefaultPermissionAdapter();
   const router = options.router ?? createDefaultRouterAdapter();
   const http = options.http ?? createFetchHttpAdapter();
@@ -492,12 +536,16 @@ function createRuntimeContext(options = {}) {
     dataSources: options.dataSources ?? {},
     services,
     http,
-    getScope: () => buildScope(context)
+    getScope: () => buildScope(context),
+    localizationMode: options.localizationMode
   });
   const dslSources = new DslSourceResolver({
     services,
     http,
-    getScope: () => buildScope(context)
+    getScope: () => buildScope(context),
+    localizationMode: options.localizationMode,
+    // 语言上下文注入（G25）：页面运行时按语言重建，缓存键随 locale 隔离
+    locale: options.locale
   });
   context = {
     app: options.app ?? {},
@@ -518,17 +566,18 @@ function createRuntimeContext(options = {}) {
     http,
     dslSources,
     locale: options.locale ?? "zh-CN",
-    i18n: (0, import_core.createI18nContext)({
+    i18n: (0, import_core2.createI18nContext)({
       locale: options.locale,
       defaultLocale: options.defaultLocale,
       messages: options.messages
-    })
+    }),
+    localizationMode: options.localizationMode ?? "client"
   };
   return context;
 }
 
 // src/context/i18n-context.ts
-var import_core2 = require("@pactor-app/core");
+var import_core3 = require("@pactor-app/core");
 var import_react = require("react");
 
 // src/context/locales/en-US.ts
@@ -1141,7 +1190,7 @@ var defaultMessages = {
 var I18nReactContext = (0, import_react.createContext)(null);
 var I18nContextProvider = I18nReactContext.Provider;
 function createDefaultI18n(locale) {
-  return (0, import_core2.createI18nContext)({ locale, messages: defaultMessages });
+  return (0, import_core3.createI18nContext)({ locale, messages: defaultMessages });
 }
 var defaultI18n = createDefaultI18n();
 function useI18n() {
@@ -1425,6 +1474,7 @@ var ActionEngine = class {
         // Renderer 的 resolveProps）保持原样，由各自执行/渲染时
         // 按当时的 state 与作用域求值
         params: resolveDeep(action.params ?? {}, scope, {
+          localizationMode: this.context.localizationMode,
           isOpaque: (value) => typeof value["action"] === "string" || typeof value["type"] === "string" || typeof value["component"] === "string"
         })
       };
@@ -1460,13 +1510,13 @@ var ActionEngine = class {
 };
 
 // src/renderer/renderer.tsx
-var import_core4 = require("@pactor-app/core");
+var import_core5 = require("@pactor-app/core");
 var import_expression3 = require("@pactor-app/expression");
 var import_schema = require("@pactor-app/schema");
 var import_react4 = require("react");
 
 // src/renderer/dsl-source-boundary.tsx
-var import_core3 = require("@pactor-app/core");
+var import_core4 = require("@pactor-app/core");
 var import_react2 = require("react");
 var import_jsx_runtime = require("react/jsx-runtime");
 function DslSourceBoundary({
@@ -1486,7 +1536,7 @@ function DslSourceBoundary({
         if (cancelled) {
           return;
         }
-        if ((0, import_core3.isDslFragmentPayload)(content)) {
+        if ((0, import_core4.isDslFragmentPayload)(content)) {
           if (content.state) {
             context.state.set(content.state);
           }
@@ -1630,7 +1680,7 @@ function renderNode(node, value, key) {
       referenceStack: [...stack, name]
     };
     scoped.renderChildren = (children, extraScope) => renderChildrenOf(scoped, children, extraScope);
-    if ((0, import_core4.isDslSourceRef)(subtree)) {
+    if ((0, import_core5.isDslSourceRef)(subtree)) {
       const ref = subtree;
       return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(RendererContextProvider, { value: scoped, children: /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
         DslSourceBoundary,
@@ -1678,7 +1728,7 @@ function renderNode(node, value, key) {
   if (!normalized) {
     return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(UnsupportedComponent, { type: node.type }, key);
   }
-  const props = resolveProps(node.props, scope);
+  const props = resolveProps(node.props, scope, value.context.localizationMode);
   if (node.events) {
     for (const [name, actions] of Object.entries(node.events)) {
       props[name] = (event) => {
@@ -1732,7 +1782,7 @@ function validateResolvedNode(content, label) {
   return content;
 }
 function validateResolvedNodes(content, label) {
-  if ((0, import_core4.isDslFragmentPayload)(content)) {
+  if ((0, import_core5.isDslFragmentPayload)(content)) {
     const errors2 = (0, import_schema.validateDslFragmentPayload)(content);
     if (errors2.length > 0) {
       console.warn(
@@ -1754,7 +1804,7 @@ function validateResolvedNodes(content, label) {
   return content;
 }
 function renderChildItem(value, item, key) {
-  if ((0, import_core4.isDslSourceRef)(item)) {
+  if ((0, import_core5.isDslSourceRef)(item)) {
     const ref = item;
     return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
       DslSourceBoundary,
@@ -1768,7 +1818,7 @@ function renderChildItem(value, item, key) {
             return null;
           }
           return nodes.map(
-            (child, index) => renderChildItem(value, child, (0, import_core4.isDslSourceRef)(child) ? `ref-${index}` : child.id ?? index)
+            (child, index) => renderChildItem(value, child, (0, import_core5.isDslSourceRef)(child) ? `ref-${index}` : child.id ?? index)
           );
         }
       },
@@ -1781,7 +1831,7 @@ function renderChildrenOf(value, children, extraScope) {
   if (!children || Array.isArray(children) && children.length === 0) {
     return null;
   }
-  if ((0, import_core4.isDslSourceRef)(children)) {
+  if ((0, import_core5.isDslSourceRef)(children)) {
     const ref = children;
     return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
       DslSourceBoundary,
@@ -1795,14 +1845,14 @@ function renderChildrenOf(value, children, extraScope) {
             return null;
           }
           return nodes.map(
-            (child, index) => renderChildItem(value, child, (0, import_core4.isDslSourceRef)(child) ? `ref-${index}` : child.id ?? index)
+            (child, index) => renderChildItem(value, child, (0, import_core5.isDslSourceRef)(child) ? `ref-${index}` : child.id ?? index)
           );
         }
       },
       "dsl-source"
     );
   }
-  const itemKey = (child, index) => (0, import_core4.isDslSourceRef)(child) ? `ref-${index}` : child.id ?? index;
+  const itemKey = (child, index) => (0, import_core5.isDslSourceRef)(child) ? `ref-${index}` : child.id ?? index;
   if (!extraScope) {
     return children.map(
       (child, index) => renderChildItem(value, child, itemKey(child, index))
@@ -1828,13 +1878,16 @@ function normalizeEntry(entry) {
   }
   return { component: entry };
 }
-function resolveProps(props, scope) {
+function resolveProps(props, scope, localizationMode) {
   if (!props) {
     return {};
   }
   const out = {};
   for (const [key, value] of Object.entries(props)) {
-    out[key] = typeof value === "string" && key.startsWith("on") ? value : resolveDeep(value, scope, { isOpaque: isEmbeddedDslNode });
+    out[key] = typeof value === "string" && key.startsWith("on") ? value : resolveDeep(value, scope, {
+      isOpaque: isEmbeddedDslNode,
+      localizationMode
+    });
   }
   return out;
 }
@@ -1843,7 +1896,7 @@ function isEmbeddedDslNode(value) {
 }
 
 // src/page/page-runtime.tsx
-var import_core5 = require("@pactor-app/core");
+var import_core6 = require("@pactor-app/core");
 var import_schema2 = require("@pactor-app/schema");
 var import_jsx_runtime4 = require("react/jsx-runtime");
 var PageRuntimeError = class extends Error {
@@ -1933,7 +1986,7 @@ function PageRuntimeView({
   return renderRoots(runtime.pageDsl, runtime.context, runtime.engine, children);
 }
 function renderRoots(pageDsl, context, engine, children) {
-  if (!pageDsl.body && (0, import_core5.isDslSourceRef)(pageDsl.children)) {
+  if (!pageDsl.body && (0, import_core6.isDslSourceRef)(pageDsl.children)) {
     const ref = pageDsl.children;
     return /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(
       DslSourceBoundary,
@@ -1945,14 +1998,14 @@ function renderRoots(pageDsl, context, engine, children) {
       }
     );
   }
-  const roots = (0, import_core5.resolveRootNodes)(pageDsl);
+  const roots = (0, import_core6.resolveRootNodes)(pageDsl);
   if (roots.length === 0) {
     return /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(import_jsx_runtime4.Fragment, { children: children ?? null });
   }
   return renderRootItems(roots, context, engine, children);
 }
 function renderResolvedRoots(content, context, engine, children) {
-  if ((0, import_core5.isDslFragmentPayload)(content)) {
+  if ((0, import_core6.isDslFragmentPayload)(content)) {
     const fragmentErrors = (0, import_schema2.validateDslFragmentPayload)(content);
     if (fragmentErrors.length > 0) {
       console.warn(
@@ -1980,7 +2033,7 @@ function renderResolvedRoots(content, context, engine, children) {
 }
 function renderRootItems(items, context, engine, children) {
   return /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(import_jsx_runtime4.Fragment, { children: items.map(
-    (item, index) => (0, import_core5.isDslSourceRef)(item) ? /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(
+    (item, index) => (0, import_core6.isDslSourceRef)(item) ? /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(
       DslSourceBoundary,
       {
         context,
@@ -2009,6 +2062,7 @@ function renderRootItems(items, context, engine, children) {
   DslSourceBoundary,
   DslSourceResolver,
   I18nContextProvider,
+  LocalizationProtocolError,
   PageRuntimeError,
   PageRuntimeView,
   StateStore,

package/dist/index.d.cts

@@ -89,6 +89,39 @@ declare class ActionEngine {
     executeAll(actions: ActionConfig | ActionConfig[], localScope?: ExpressionScope): Promise<ActionResult[]>;
 }
 
+/**
+ * 本地化协议模式：
+ * - `client`（默认）：作者态 `$i18n` 描述按普通对象递归（行为同历史版本）
+ * - `server`：本地化已在服务端完成，作者态 `$i18n` 出现在解析路径即协议错误
+ */
+type LocalizationMode = 'client' | 'server';
+/** 本地化协议错误：server 模式下作者态 `$i18n` 漏入客户端解析路径时抛出 */
+declare class LocalizationProtocolError extends Error {
+    constructor(message: string);
+}
+interface ResolveDeepOptions {
+    /**
+     * 返回 true 时该对象（及其子树）不求值、原样保留。
+     * Action 引擎用它跳过 params 中内嵌的子动作配置
+     * （`sequence` / `parallel` / `if` 的子动作须在各自执行时
+     * 按当时的 state 求值，不能随父动作提前求值）。
+     */
+    isOpaque?: (value: Record<string, unknown>) => boolean;
+    /** 本地化协议模式（缺省 `client`）；`server` 模式下拒绝作者态 `$i18n` */
+    localizationMode?: LocalizationMode;
+}
+/**
+ * 深度表达式求值（设计文档第 21 节，D5）：
+ *
+ * - 字符串经 @pactor-app/expression `resolveTemplate` 求值
+ *   （整体单表达式保留原始类型，无 `${` 快速返回）
+ * - `$localizedText` 包装对象经独立插值路径解析为终值字符串
+ * - `localizationMode: 'server'` 时作者态 `$i18n` 描述为协议错误
+ * - 数组 / 普通对象递归处理
+ * - 其余类型原样保留
+ */
+declare function resolveDeep(value: unknown, scope: ExpressionScope, options?: ResolveDeepOptions): unknown;
+
 /** 单个数据源的运行时状态 */
 interface DataSourceStatus {
     loading: boolean;
@@ -101,6 +134,8 @@ interface DataStoreDeps {
     http: HttpAdapter;
     /** 加载前取当前表达式作用域（params / request 求值用） */
     getScope: () => ExpressionScope;
+    /** 本地化协议模式（缺省 'client'），透传给 params / request 求值 */
+    localizationMode?: LocalizationMode;
 }
 /**
  * DataStore：DataSource 运行时（设计文档第 19 节，决策 D3）。
@@ -114,6 +149,7 @@ declare class DataStore {
     private readonly services;
     private readonly http;
     private readonly getScope;
+    private readonly localizationMode?;
     private readonly statuses;
     private readonly listeners;
     private version;
@@ -168,15 +204,26 @@ interface DslSourceResolverDeps {
     http: HttpAdapter;
     /** 加载前取当前表达式作用域（params 求值用） */
     getScope: () => ExpressionScope;
+    /** 本地化协议模式（缺省 'client'），透传给 params / request 求值 */
+    localizationMode?: LocalizationMode;
+    /**
+     * 当前语言代码（G25 注入点，runtime 不依赖 app/i18n 包）：纳入缓存键，
+     * 语言上下文不同的解析器互不命中；缺省维持旧键形（仅引用原文）
+     */
+    locale?: string;
 }
-/** 缓存 key：按固定字段序拼接引用原文（避免字段顺序差异导致重复请求） */
-declare function dslSourceKey(ref: DslSourceRef): string;
+/**
+ * 缓存 key：按固定字段序拼接引用原文（避免字段顺序差异导致重复请求）；
+ * locale 给出时前置语言上下文（G25），缺省维持旧键形（仅引用原文）。
+ */
+declare function dslSourceKey(ref: DslSourceRef, locale?: string): string;
 /**
  * DslSourceResolver（spec: dsl-renderer 动态引用解析）：
  * 按 `source.type` 分派——service 经 ServiceRegistry、http 经 HttpAdapter；
  * `params` 表达式按**首次解析时**作用域求值一次（不做联动重载）。
  * 结果按引用原文缓存于页面运行时生命周期（Promise 级去重：并发渲染
- * 同一引用共享一次请求；失败同样缓存，随运行时销毁清理）。
+ * 同一引用共享一次请求；失败同样缓存，随运行时销毁清理）；
+ * 注入 `locale` 时缓存键前置语言上下文，跨语言互不命中。
  */
 declare class DslSourceResolver {
     private readonly deps;
@@ -297,6 +344,12 @@ interface RuntimeContext {
     locale: string;
     /** i18n 上下文：提供 `t(key, params?)` 翻译函数 */
     i18n: I18nContext;
+    /**
+     * 本地化协议模式（缺省 'client'）：'server' 时 props / 动作参数 /
+     * dataSource 参数解析路径中遇到作者态 `$i18n` 描述抛
+     * LocalizationProtocolError；'client' 行为与历史版本一致
+     */
+    localizationMode: LocalizationMode;
     /**
      * 子运行时指回创建它的宿主运行时上下文（如 OverlayHost 为 page
      * 类型弹层创建的子 PageRuntime）。交互归属（overlay 在哪个宿主的
@@ -333,6 +386,8 @@ interface CreateRuntimeContextOptions {
     defaultLocale?: string;
     /** 翻译消息表 */
     messages?: Record<string, string | Record<string, string>>;
+    /** 本地化协议模式（缺省 'client'）；'server' 时 `$i18n` 漏入解析路径为协议错误 */
+    localizationMode?: LocalizationMode;
 }
 /**
  * 组装 RuntimeContext。默认情形下 registries 为空 Registry 实例、
@@ -516,23 +571,4 @@ declare function PageRuntimeView({ runtime, children, }: {
     children?: ReactNode;
 }): ReactNode;
 
-interface ResolveDeepOptions {
-    /**
-     * 返回 true 时该对象（及其子树）不求值、原样保留。
-     * Action 引擎用它跳过 params 中内嵌的子动作配置
-     * （`sequence` / `parallel` / `if` 的子动作须在各自执行时
-     * 按当时的 state 求值，不能随父动作提前求值）。
-     */
-    isOpaque?: (value: Record<string, unknown>) => boolean;
-}
-/**
- * 深度表达式求值（设计文档第 21 节，D5）：
- *
- * - 字符串经 @pactor-app/expression `resolveTemplate` 求值
- *   （整体单表达式保留原始类型，无 `${` 快速返回）
- * - 数组 / 普通对象递归处理
- * - 其余类型原样保留
- */
-declare function resolveDeep(value: unknown, scope: ExpressionScope, options?: ResolveDeepOptions): unknown;
-
-export { type ActionContext, ActionEngine, type ActionHandler, type ActionRegistry, type ActionResult, type CapabilityRegistry, type ComponentEntry, type ComponentRegistry, type CreateRuntimeContextOptions, type DataSourceStatus, DataStore, type DataStoreDeps, DslRenderer, type DslRendererProps, DslSourceBoundary, type DslSourceBoundaryProps, DslSourceResolver, type DslSourceResolverDeps, type FormHandle, type FormRegistry, type HttpAdapter, type HttpRequestConfig, I18nContextProvider, type LocalScope, type PageRuntime, PageRuntimeError, PageRuntimeView, type PermissionAdapter, type RendererContextValue, type RouteContext, type RouterAdapter, type RuntimeContext, type ScopedComponentEntry, type ServiceHandler, type ServiceRegistry, StateStore, UnsupportedComponent, buildScope, createDefaultPermissionAdapter, createDefaultRouterAdapter, createFetchHttpAdapter, createPageRuntime, createRuntimeContext, dslSourceKey, registerBuiltinActions, resolveDeep, useDataSource, useI18n, useRenderer, useRuntimeState };
+export { type ActionContext, ActionEngine, type ActionHandler, type ActionRegistry, type ActionResult, type CapabilityRegistry, type ComponentEntry, type ComponentRegistry, type CreateRuntimeContextOptions, type DataSourceStatus, DataStore, type DataStoreDeps, DslRenderer, type DslRendererProps, DslSourceBoundary, type DslSourceBoundaryProps, DslSourceResolver, type DslSourceResolverDeps, type FormHandle, type FormRegistry, type HttpAdapter, type HttpRequestConfig, I18nContextProvider, type LocalScope, type LocalizationMode, LocalizationProtocolError, type PageRuntime, PageRuntimeError, PageRuntimeView, type PermissionAdapter, type RendererContextValue, type ResolveDeepOptions, type RouteContext, type RouterAdapter, type RuntimeContext, type ScopedComponentEntry, type ServiceHandler, type ServiceRegistry, StateStore, UnsupportedComponent, buildScope, createDefaultPermissionAdapter, createDefaultRouterAdapter, createFetchHttpAdapter, createPageRuntime, createRuntimeContext, dslSourceKey, registerBuiltinActions, resolveDeep, useDataSource, useI18n, useRenderer, useRuntimeState };

package/dist/index.d.ts

@@ -89,6 +89,39 @@ declare class ActionEngine {
     executeAll(actions: ActionConfig | ActionConfig[], localScope?: ExpressionScope): Promise<ActionResult[]>;
 }
 
+/**
+ * 本地化协议模式：
+ * - `client`（默认）：作者态 `$i18n` 描述按普通对象递归（行为同历史版本）
+ * - `server`：本地化已在服务端完成，作者态 `$i18n` 出现在解析路径即协议错误
+ */
+type LocalizationMode = 'client' | 'server';
+/** 本地化协议错误：server 模式下作者态 `$i18n` 漏入客户端解析路径时抛出 */
+declare class LocalizationProtocolError extends Error {
+    constructor(message: string);
+}
+interface ResolveDeepOptions {
+    /**
+     * 返回 true 时该对象（及其子树）不求值、原样保留。
+     * Action 引擎用它跳过 params 中内嵌的子动作配置
+     * （`sequence` / `parallel` / `if` 的子动作须在各自执行时
+     * 按当时的 state 求值，不能随父动作提前求值）。
+     */
+    isOpaque?: (value: Record<string, unknown>) => boolean;
+    /** 本地化协议模式（缺省 `client`）；`server` 模式下拒绝作者态 `$i18n` */
+    localizationMode?: LocalizationMode;
+}
+/**
+ * 深度表达式求值（设计文档第 21 节，D5）：
+ *
+ * - 字符串经 @pactor-app/expression `resolveTemplate` 求值
+ *   （整体单表达式保留原始类型，无 `${` 快速返回）
+ * - `$localizedText` 包装对象经独立插值路径解析为终值字符串
+ * - `localizationMode: 'server'` 时作者态 `$i18n` 描述为协议错误
+ * - 数组 / 普通对象递归处理
+ * - 其余类型原样保留
+ */
+declare function resolveDeep(value: unknown, scope: ExpressionScope, options?: ResolveDeepOptions): unknown;
+
 /** 单个数据源的运行时状态 */
 interface DataSourceStatus {
     loading: boolean;
@@ -101,6 +134,8 @@ interface DataStoreDeps {
     http: HttpAdapter;
     /** 加载前取当前表达式作用域（params / request 求值用） */
     getScope: () => ExpressionScope;
+    /** 本地化协议模式（缺省 'client'），透传给 params / request 求值 */
+    localizationMode?: LocalizationMode;
 }
 /**
  * DataStore：DataSource 运行时（设计文档第 19 节，决策 D3）。
@@ -114,6 +149,7 @@ declare class DataStore {
     private readonly services;
     private readonly http;
     private readonly getScope;
+    private readonly localizationMode?;
     private readonly statuses;
     private readonly listeners;
     private version;
@@ -168,15 +204,26 @@ interface DslSourceResolverDeps {
     http: HttpAdapter;
     /** 加载前取当前表达式作用域（params 求值用） */
     getScope: () => ExpressionScope;
+    /** 本地化协议模式（缺省 'client'），透传给 params / request 求值 */
+    localizationMode?: LocalizationMode;
+    /**
+     * 当前语言代码（G25 注入点，runtime 不依赖 app/i18n 包）：纳入缓存键，
+     * 语言上下文不同的解析器互不命中；缺省维持旧键形（仅引用原文）
+     */
+    locale?: string;
 }
-/** 缓存 key：按固定字段序拼接引用原文（避免字段顺序差异导致重复请求） */
-declare function dslSourceKey(ref: DslSourceRef): string;
+/**
+ * 缓存 key：按固定字段序拼接引用原文（避免字段顺序差异导致重复请求）；
+ * locale 给出时前置语言上下文（G25），缺省维持旧键形（仅引用原文）。
+ */
+declare function dslSourceKey(ref: DslSourceRef, locale?: string): string;
 /**
  * DslSourceResolver（spec: dsl-renderer 动态引用解析）：
  * 按 `source.type` 分派——service 经 ServiceRegistry、http 经 HttpAdapter；
  * `params` 表达式按**首次解析时**作用域求值一次（不做联动重载）。
  * 结果按引用原文缓存于页面运行时生命周期（Promise 级去重：并发渲染
- * 同一引用共享一次请求；失败同样缓存，随运行时销毁清理）。
+ * 同一引用共享一次请求；失败同样缓存，随运行时销毁清理）；
+ * 注入 `locale` 时缓存键前置语言上下文，跨语言互不命中。
  */
 declare class DslSourceResolver {
     private readonly deps;
@@ -297,6 +344,12 @@ interface RuntimeContext {
     locale: string;
     /** i18n 上下文：提供 `t(key, params?)` 翻译函数 */
     i18n: I18nContext;
+    /**
+     * 本地化协议模式（缺省 'client'）：'server' 时 props / 动作参数 /
+     * dataSource 参数解析路径中遇到作者态 `$i18n` 描述抛
+     * LocalizationProtocolError；'client' 行为与历史版本一致
+     */
+    localizationMode: LocalizationMode;
     /**
      * 子运行时指回创建它的宿主运行时上下文（如 OverlayHost 为 page
      * 类型弹层创建的子 PageRuntime）。交互归属（overlay 在哪个宿主的
@@ -333,6 +386,8 @@ interface CreateRuntimeContextOptions {
     defaultLocale?: string;
     /** 翻译消息表 */
     messages?: Record<string, string | Record<string, string>>;
+    /** 本地化协议模式（缺省 'client'）；'server' 时 `$i18n` 漏入解析路径为协议错误 */
+    localizationMode?: LocalizationMode;
 }
 /**
  * 组装 RuntimeContext。默认情形下 registries 为空 Registry 实例、
@@ -516,23 +571,4 @@ declare function PageRuntimeView({ runtime, children, }: {
     children?: ReactNode;
 }): ReactNode;
 
-interface ResolveDeepOptions {
-    /**
-     * 返回 true 时该对象（及其子树）不求值、原样保留。
-     * Action 引擎用它跳过 params 中内嵌的子动作配置
-     * （`sequence` / `parallel` / `if` 的子动作须在各自执行时
-     * 按当时的 state 求值，不能随父动作提前求值）。
-     */
-    isOpaque?: (value: Record<string, unknown>) => boolean;
-}
-/**
- * 深度表达式求值（设计文档第 21 节，D5）：
- *
- * - 字符串经 @pactor-app/expression `resolveTemplate` 求值
- *   （整体单表达式保留原始类型，无 `${` 快速返回）
- * - 数组 / 普通对象递归处理
- * - 其余类型原样保留
- */
-declare function resolveDeep(value: unknown, scope: ExpressionScope, options?: ResolveDeepOptions): unknown;
-
-export { type ActionContext, ActionEngine, type ActionHandler, type ActionRegistry, type ActionResult, type CapabilityRegistry, type ComponentEntry, type ComponentRegistry, type CreateRuntimeContextOptions, type DataSourceStatus, DataStore, type DataStoreDeps, DslRenderer, type DslRendererProps, DslSourceBoundary, type DslSourceBoundaryProps, DslSourceResolver, type DslSourceResolverDeps, type FormHandle, type FormRegistry, type HttpAdapter, type HttpRequestConfig, I18nContextProvider, type LocalScope, type PageRuntime, PageRuntimeError, PageRuntimeView, type PermissionAdapter, type RendererContextValue, type RouteContext, type RouterAdapter, type RuntimeContext, type ScopedComponentEntry, type ServiceHandler, type ServiceRegistry, StateStore, UnsupportedComponent, buildScope, createDefaultPermissionAdapter, createDefaultRouterAdapter, createFetchHttpAdapter, createPageRuntime, createRuntimeContext, dslSourceKey, registerBuiltinActions, resolveDeep, useDataSource, useI18n, useRenderer, useRuntimeState };
+export { type ActionContext, ActionEngine, type ActionHandler, type ActionRegistry, type ActionResult, type CapabilityRegistry, type ComponentEntry, type ComponentRegistry, type CreateRuntimeContextOptions, type DataSourceStatus, DataStore, type DataStoreDeps, DslRenderer, type DslRendererProps, DslSourceBoundary, type DslSourceBoundaryProps, DslSourceResolver, type DslSourceResolverDeps, type FormHandle, type FormRegistry, type HttpAdapter, type HttpRequestConfig, I18nContextProvider, type LocalScope, type LocalizationMode, LocalizationProtocolError, type PageRuntime, PageRuntimeError, PageRuntimeView, type PermissionAdapter, type RendererContextValue, type ResolveDeepOptions, type RouteContext, type RouterAdapter, type RuntimeContext, type ScopedComponentEntry, type ServiceHandler, type ServiceRegistry, StateStore, UnsupportedComponent, buildScope, createDefaultPermissionAdapter, createDefaultRouterAdapter, createFetchHttpAdapter, createPageRuntime, createRuntimeContext, dslSourceKey, registerBuiltinActions, resolveDeep, useDataSource, useI18n, useRenderer, useRuntimeState };

package/dist/index.js

@@ -64,6 +64,10 @@ function createFetchHttpAdapter() {
 import { Registry, createI18nContext } from "@pactor-app/core";
 
 // src/utils/resolve.ts
+import {
+  isI18nDescriptor,
+  isLocalizedText
+} from "@pactor-app/core";
 import {
   hasExpression,
   resolveTemplate
@@ -71,6 +75,34 @@ import {
 function isPlainRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+var LocalizationProtocolError = class extends Error {
+  constructor(message) {
+    super(`[@pactor-app/runtime] ${message}`);
+    this.name = "LocalizationProtocolError";
+  }
+};
+function interpolateLocalizedText(template, params) {
+  return template.replace(/\{\{(\w+)\}\}/g, (match, name) => {
+    const value = params[name];
+    if (value === void 0 || value === null) {
+      console.warn(
+        `[@pactor-app/runtime] $localizedText \u672A\u77E5\u53C2\u6570 "${name}"\uFF0C\u4FDD\u7559\u5360\u4F4D\u7B26 ${match}`
+      );
+      return match;
+    }
+    return String(value);
+  });
+}
+function resolveLocalizedText(value, scope, options) {
+  const { template, params } = value.$localizedText;
+  const resolvedParams = {};
+  if (isPlainRecord(params)) {
+    for (const [key, item] of Object.entries(params)) {
+      resolvedParams[key] = resolveDeep(item, scope, options);
+    }
+  }
+  return interpolateLocalizedText(template, resolvedParams);
+}
 function resolveDeep(value, scope, options = {}) {
   if (typeof value === "string") {
     return hasExpression(value) ? resolveTemplate(value, scope) : value;
@@ -79,6 +111,14 @@ function resolveDeep(value, scope, options = {}) {
     return value.map((item) => resolveDeep(item, scope, options));
   }
   if (isPlainRecord(value)) {
+    if (options.localizationMode === "server" && isI18nDescriptor(value)) {
+      throw new LocalizationProtocolError(
+        "server \u672C\u5730\u5316\u6A21\u5F0F\u4E0B\u4F5C\u8005\u6001 `$i18n` \u4E0D\u5141\u8BB8\u51FA\u73B0\u5728\u5BA2\u6237\u7AEF\u89E3\u6790\u8DEF\u5F84"
+      );
+    }
+    if (isLocalizedText(value)) {
+      return resolveLocalizedText(value, scope, options);
+    }
     if (options.isOpaque?.(value)) {
       return value;
     }
@@ -104,6 +144,7 @@ var DataStore = class {
     this.services = deps.services;
     this.http = deps.http;
     this.getScope = deps.getScope;
+    this.localizationMode = deps.localizationMode;
     for (const name of Object.keys(deps.dataSources)) {
       this.statuses.set(name, { loading: false });
     }
@@ -237,7 +278,9 @@ var DataStore = class {
             `[@pactor-app/runtime] service not registered: "${serviceName}"`
           );
         }
-        const params = resolveDeep(config.params ?? {}, this.getScope());
+        const params = resolveDeep(config.params ?? {}, this.getScope(), {
+          localizationMode: this.localizationMode
+        });
         return handler(params);
       }
       case "http": {
@@ -246,7 +289,8 @@ var DataStore = class {
         }
         const request = resolveDeep(
           config.request,
-          this.getScope()
+          this.getScope(),
+          { localizationMode: this.localizationMode }
         );
         return this.http.request(request);
       }
@@ -291,13 +335,10 @@ function applyOptionMapping(data, config) {
 }
 
 // src/datasource/dsl-source-resolver.ts
-function dslSourceKey(ref) {
+function dslSourceKey(ref, locale) {
   const source = ref.source;
-  if (source.type === "service") {
-    return `service:${source.service}:${JSON.stringify(source.params ?? {})}`;
-  }
-  const request = source.request;
-  return `http:${(request.method ?? "GET").toUpperCase()}:${request.url}:${JSON.stringify(request.params ?? {})}:${JSON.stringify(request.headers ?? {})}`;
+  const base = source.type === "service" ? `service:${source.service}:${JSON.stringify(source.params ?? {})}` : `http:${(source.request.method ?? "GET").toUpperCase()}:${source.request.url}:${JSON.stringify(source.request.params ?? {})}:${JSON.stringify(source.request.headers ?? {})}`;
+  return locale ? `${locale}|${base}` : base;
 }
 var DslSourceResolver = class {
   constructor(deps) {
@@ -305,7 +346,7 @@ var DslSourceResolver = class {
     this.cache = /* @__PURE__ */ new Map();
   }
   resolve(ref) {
-    const key = dslSourceKey(ref);
+    const key = dslSourceKey(ref, this.deps.locale);
     let cached = this.cache.get(key);
     if (cached === void 0) {
       cached = this.load(ref);
@@ -315,6 +356,7 @@ var DslSourceResolver = class {
   }
   async load(ref) {
     const scope = this.deps.getScope();
+    const resolveOptions = { localizationMode: this.deps.localizationMode };
     const source = ref.source;
     if (source.type === "service") {
       const handler = this.deps.services.get(source.service);
@@ -323,10 +365,14 @@ var DslSourceResolver = class {
           `[@pactor-app/runtime] service not registered: "${source.service}"`
         );
       }
-      const params = resolveDeep(source.params ?? {}, scope);
+      const params = resolveDeep(source.params ?? {}, scope, resolveOptions);
       return handler(params);
     }
-    const request = resolveDeep(source.request, scope);
+    const request = resolveDeep(
+      source.request,
+      scope,
+      resolveOptions
+    );
     return this.deps.http.request(request);
   }
 };
@@ -447,12 +493,16 @@ function createRuntimeContext(options = {}) {
     dataSources: options.dataSources ?? {},
     services,
     http,
-    getScope: () => buildScope(context)
+    getScope: () => buildScope(context),
+    localizationMode: options.localizationMode
   });
   const dslSources = new DslSourceResolver({
     services,
     http,
-    getScope: () => buildScope(context)
+    getScope: () => buildScope(context),
+    localizationMode: options.localizationMode,
+    // 语言上下文注入（G25）：页面运行时按语言重建，缓存键随 locale 隔离
+    locale: options.locale
   });
   context = {
     app: options.app ?? {},
@@ -477,7 +527,8 @@ function createRuntimeContext(options = {}) {
       locale: options.locale,
       defaultLocale: options.defaultLocale,
       messages: options.messages
-    })
+    }),
+    localizationMode: options.localizationMode ?? "client"
   };
   return context;
 }
@@ -1382,6 +1433,7 @@ var ActionEngine = class {
         // Renderer 的 resolveProps）保持原样，由各自执行/渲染时
         // 按当时的 state 与作用域求值
         params: resolveDeep(action.params ?? {}, scope, {
+          localizationMode: this.context.localizationMode,
           isOpaque: (value) => typeof value["action"] === "string" || typeof value["type"] === "string" || typeof value["component"] === "string"
         })
       };
@@ -1645,7 +1697,7 @@ function renderNode(node, value, key) {
   if (!normalized) {
     return /* @__PURE__ */ jsx2(UnsupportedComponent, { type: node.type }, key);
   }
-  const props = resolveProps(node.props, scope);
+  const props = resolveProps(node.props, scope, value.context.localizationMode);
   if (node.events) {
     for (const [name, actions] of Object.entries(node.events)) {
       props[name] = (event) => {
@@ -1795,13 +1847,16 @@ function normalizeEntry(entry) {
   }
   return { component: entry };
 }
-function resolveProps(props, scope) {
+function resolveProps(props, scope, localizationMode) {
   if (!props) {
     return {};
   }
   const out = {};
   for (const [key, value] of Object.entries(props)) {
-    out[key] = typeof value === "string" && key.startsWith("on") ? value : resolveDeep(value, scope, { isOpaque: isEmbeddedDslNode });
+    out[key] = typeof value === "string" && key.startsWith("on") ? value : resolveDeep(value, scope, {
+      isOpaque: isEmbeddedDslNode,
+      localizationMode
+    });
   }
   return out;
 }
@@ -1979,6 +2034,7 @@ export {
   DslSourceBoundary,
   DslSourceResolver,
   I18nContextProvider,
+  LocalizationProtocolError,
   PageRuntimeError,
   PageRuntimeView,
   StateStore,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pactor-app/runtime",
-  "version": "1.54.4",
+  "version": "1.55.0",
   "description": "Pactor runtime: RuntimeContext, StateStore, DataSource runtime, action engine, React renderer and page runtime",
   "keywords": [
     "pactor",
@@ -45,9 +45,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@pactor-app/core": "1.54.4",
-    "@pactor-app/expression": "1.54.4",
-    "@pactor-app/schema": "1.54.4"
+    "@pactor-app/core": "1.55.0",
+    "@pactor-app/schema": "1.55.0",
+    "@pactor-app/expression": "1.55.0"
   },
   "peerDependencies": {
     "react": ">=18"