@nocobase/shared 3.0.0-alpha.1 → 3.0.0-alpha.12

package/lib/index.d.ts

@@ -7,4 +7,5 @@
  * For more information, please refer to: https://www.nocobase.com/agreement.
  */
 export * from './getValuesByPath';
+export * from './ui-operation';
 export * from './variable-usage';

package/lib/index.js

@@ -24,9 +24,11 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var src_exports = {};
 module.exports = __toCommonJS(src_exports);
 __reExport(src_exports, require("./getValuesByPath"), module.exports);
+__reExport(src_exports, require("./ui-operation"), module.exports);
 __reExport(src_exports, require("./variable-usage"), module.exports);
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ...require("./getValuesByPath"),
+  ...require("./ui-operation"),
   ...require("./variable-usage")
 });

package/lib/ui-operation.d.ts

@@ -0,0 +1,25 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+export declare const UI_OPERATION_QUERY_KEY = "_operation_";
+export declare const UI_OPERATION_VERSION = 1;
+export declare const MAX_UI_OPERATION_ENCODED_LENGTH: number;
+export interface UIOperation<TOperationId extends string = string, TParams extends Record<string, unknown> = Record<string, unknown>> {
+    v: typeof UI_OPERATION_VERSION;
+    operationId: TOperationId;
+    params?: TParams;
+}
+export interface UIOperationCodec {
+    encode(value: string): string;
+    decode(value: string): string | undefined;
+}
+export declare function isUIOperation(value: unknown): value is UIOperation;
+export declare function encodeUIOperation(operation: UIOperation, codec: UIOperationCodec): string;
+export declare function decodeUIOperation(encoded: string, codec: UIOperationCodec): UIOperation | undefined;
+export declare function parseUIOperation(search: string, codec: UIOperationCodec): UIOperation | undefined;
+export declare function removeUIOperation(search: string): string;

package/lib/ui-operation.js

@@ -0,0 +1,114 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+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 __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var ui_operation_exports = {};
+__export(ui_operation_exports, {
+  MAX_UI_OPERATION_ENCODED_LENGTH: () => MAX_UI_OPERATION_ENCODED_LENGTH,
+  UI_OPERATION_QUERY_KEY: () => UI_OPERATION_QUERY_KEY,
+  UI_OPERATION_VERSION: () => UI_OPERATION_VERSION,
+  decodeUIOperation: () => decodeUIOperation,
+  encodeUIOperation: () => encodeUIOperation,
+  isUIOperation: () => isUIOperation,
+  parseUIOperation: () => parseUIOperation,
+  removeUIOperation: () => removeUIOperation
+});
+module.exports = __toCommonJS(ui_operation_exports);
+const UI_OPERATION_QUERY_KEY = "_operation_";
+const UI_OPERATION_VERSION = 1;
+const MAX_UI_OPERATION_ENCODED_LENGTH = 8 * 1024;
+function isPlainObject(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+__name(isPlainObject, "isPlainObject");
+function isUIOperation(value) {
+  if (!isPlainObject(value) || value.v !== UI_OPERATION_VERSION || typeof value.operationId !== "string" || !value.operationId) {
+    return false;
+  }
+  return value.params === void 0 || isPlainObject(value.params);
+}
+__name(isUIOperation, "isUIOperation");
+function encodeUIOperation(operation, codec) {
+  if (!isUIOperation(operation)) {
+    throw new TypeError("Invalid UI operation.");
+  }
+  const encoded = codec.encode(JSON.stringify(operation));
+  if (encoded.length > MAX_UI_OPERATION_ENCODED_LENGTH) {
+    throw new RangeError(`UI operation exceeds the ${MAX_UI_OPERATION_ENCODED_LENGTH}-byte encoded length limit.`);
+  }
+  return encoded;
+}
+__name(encodeUIOperation, "encodeUIOperation");
+function decodeUIOperation(encoded, codec) {
+  if (encoded.length > MAX_UI_OPERATION_ENCODED_LENGTH) {
+    return void 0;
+  }
+  try {
+    const decoded = codec.decode(encoded);
+    if (decoded === void 0) {
+      return void 0;
+    }
+    const parsed = JSON.parse(decoded);
+    return isUIOperation(parsed) ? parsed : void 0;
+  } catch {
+    return void 0;
+  }
+}
+__name(decodeUIOperation, "decodeUIOperation");
+function parseUIOperation(search, codec) {
+  try {
+    const values = new URLSearchParams(search).getAll(UI_OPERATION_QUERY_KEY);
+    if (values.length !== 1) {
+      return void 0;
+    }
+    return decodeUIOperation(values[0], codec);
+  } catch {
+    return void 0;
+  }
+}
+__name(parseUIOperation, "parseUIOperation");
+function removeUIOperation(search) {
+  const params = new URLSearchParams(search);
+  params.delete(UI_OPERATION_QUERY_KEY);
+  const remaining = params.toString();
+  return remaining ? `?${remaining}` : "";
+}
+__name(removeUIOperation, "removeUIOperation");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  MAX_UI_OPERATION_ENCODED_LENGTH,
+  UI_OPERATION_QUERY_KEY,
+  UI_OPERATION_VERSION,
+  decodeUIOperation,
+  encodeUIOperation,
+  isUIOperation,
+  parseUIOperation,
+  removeUIOperation
+});

package/lib/variable-usage.d.ts

@@ -9,6 +9,14 @@
 export type JSONValue = string | {
     [key: string]: JSONValue;
 } | JSONValue[];
+export type VariableUsageExtractionResult = {
+    unsupportedDynamicPath: boolean;
+    usage: Record<string, string[]>;
+};
+/**
+ * 提取模板中的 ctx 使用情况。该函数只做静态扫描，不执行表达式。
+ */
+export declare function extractVariableUsage(template: JSONValue): VariableUsageExtractionResult;
 /**
  * 提取模板中使用到的 ctx 顶层变量名集合。
  * - 支持点语法与顶层括号变量：ctx.user / ctx["user"]

package/lib/variable-usage.js

@@ -28,111 +28,289 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var variable_usage_exports = {};
 __export(variable_usage_exports, {
   extractUsedVariableNames: () => extractUsedVariableNames,
-  extractUsedVariablePaths: () => extractUsedVariablePaths
+  extractUsedVariablePaths: () => extractUsedVariablePaths,
+  extractVariableUsage: () => extractVariableUsage
 });
 module.exports = __toCommonJS(variable_usage_exports);
-function extractUsedVariableNames(template) {
-  const result = /* @__PURE__ */ new Set();
-  const visit = /* @__PURE__ */ __name((src) => {
-    if (typeof src === "string") {
-      const regex = /\{\{\s*([^}]+?)\s*\}\}/g;
-      let m;
-      while ((m = regex.exec(src)) !== null) {
-        const expr = m[1];
-        const pathRegex = /ctx\.([a-zA-Z_$][a-zA-Z0-9_$]*)/g;
-        let pm;
-        while ((pm = pathRegex.exec(expr)) !== null) {
-          result.add(pm[1]);
-        }
-        const bracketVarRegex = /ctx\[\s*(["'])\s*([a-zA-Z_$][a-zA-Z0-9_$]*)\s*\1\s*\]/g;
-        let bm;
-        while ((bm = bracketVarRegex.exec(expr)) !== null) {
-          result.add(bm[2]);
-        }
+function isObject(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+__name(isObject, "isObject");
+function isIdentifierStart(char) {
+  return !!char && /[a-zA-Z_$]/.test(char);
+}
+__name(isIdentifierStart, "isIdentifierStart");
+function isIdentifierPart(char) {
+  return !!char && /[a-zA-Z0-9_$]/.test(char);
+}
+__name(isIdentifierPart, "isIdentifierPart");
+function skipSpaces(input, index) {
+  let next = index;
+  while (/\s/.test(input[next] || "")) next += 1;
+  return next;
+}
+__name(skipSpaces, "skipSpaces");
+function skipPostfix(input, index) {
+  let next = skipSpaces(input, index);
+  while (input[next] === "!") {
+    next = skipSpaces(input, next + 1);
+  }
+  return next;
+}
+__name(skipPostfix, "skipPostfix");
+function previousNonSpaceIndex(input, index) {
+  let next = index;
+  while (next >= 0 && /\s/.test(input[next] || "")) next -= 1;
+  return next;
+}
+__name(previousNonSpaceIndex, "previousNonSpaceIndex");
+function isGroupedCtxReference(input, start) {
+  const openParenIndex = previousNonSpaceIndex(input, start - 1);
+  if (input[openParenIndex] !== "(") return false;
+  const beforeOpenParenIndex = previousNonSpaceIndex(input, openParenIndex - 1);
+  if (beforeOpenParenIndex < 0) return true;
+  const beforeOpenParen = input[beforeOpenParenIndex];
+  return !isIdentifierPart(beforeOpenParen) && beforeOpenParen !== ")" && beforeOpenParen !== "]";
+}
+__name(isGroupedCtxReference, "isGroupedCtxReference");
+function hasGroupedContinuation(input, index) {
+  const closeParenIndex = skipSpaces(input, index);
+  if (input[closeParenIndex] !== ")") return false;
+  const continuationIndex = skipSpaces(input, closeParenIndex + 1);
+  return input[continuationIndex] === "." || input[continuationIndex] === "[" || input.startsWith("?.", continuationIndex);
+}
+__name(hasGroupedContinuation, "hasGroupedContinuation");
+function readIdentifier(input, index) {
+  if (!isIdentifierStart(input[index])) return null;
+  let next = index + 1;
+  while (isIdentifierPart(input[next])) next += 1;
+  return { value: input.slice(index, next), next };
+}
+__name(readIdentifier, "readIdentifier");
+function readNumber(input, index) {
+  const match = input.slice(index).match(/^\d+/);
+  return match ? { value: match[0], next: index + match[0].length } : null;
+}
+__name(readNumber, "readNumber");
+function readQuotedProperty(input, index) {
+  const quote = input[index];
+  if (quote !== '"' && quote !== "'") return null;
+  let next = index + 1;
+  let value = "";
+  while (next < input.length) {
+    const char = input[next];
+    if (char === "\\") {
+      value += input.slice(next, next + 2);
+      next += 2;
+      continue;
+    }
+    if (char === quote) {
+      return { value, next: next + 1 };
+    }
+    value += char;
+    next += 1;
+  }
+  return null;
+}
+__name(readQuotedProperty, "readQuotedProperty");
+function readBracketAccess(input, index) {
+  let next = skipSpaces(input, index + 1);
+  const quoted = readQuotedProperty(input, next);
+  if (quoted) {
+    next = skipSpaces(input, quoted.next);
+    if (input[next] !== "]") return { dynamic: true };
+    return { dynamic: false, kind: "property", next: next + 1, value: quoted.value };
+  }
+  const number = readNumber(input, next);
+  if (number) {
+    next = skipSpaces(input, number.next);
+    if (input[next] !== "]") return { dynamic: true };
+    return { dynamic: false, kind: "index", next: next + 1, value: number.value };
+  }
+  return { dynamic: true };
+}
+__name(readBracketAccess, "readBracketAccess");
+function appendPathSegment(segments, kind, value) {
+  if (kind === "property") {
+    segments.push(value);
+    return;
+  }
+  if (segments.length) {
+    segments[segments.length - 1] = `${segments[segments.length - 1]}[${value}]`;
+    return;
+  }
+  segments.push(`[${value}]`);
+}
+__name(appendPathSegment, "appendPathSegment");
+function readAccess(input, index) {
+  const next = skipPostfix(input, index);
+  if (input[next] === "[") {
+    return readBracketAccess(input, next);
+  }
+  if (input.startsWith("?.", next)) {
+    const propertyStart = skipSpaces(input, next + 2);
+    if (input[propertyStart] === "[") {
+      return readBracketAccess(input, propertyStart);
+    }
+    const identifier = readIdentifier(input, propertyStart) || readNumber(input, propertyStart);
+    return identifier ? { dynamic: false, kind: "property", next: identifier.next, value: identifier.value } : null;
+  }
+  if (input[next] === ".") {
+    const propertyStart = skipSpaces(input, next + 1);
+    const identifier = readIdentifier(input, propertyStart) || readNumber(input, propertyStart);
+    return identifier ? { dynamic: false, kind: "property", next: identifier.next, value: identifier.value } : null;
+  }
+  return null;
+}
+__name(readAccess, "readAccess");
+function parseDotOnlyCtxReference(expr) {
+  const trimmed = expr.trim();
+  const segment = "(?:[a-zA-Z_$][a-zA-Z0-9_$-]*|\\d+)";
+  const match = trimmed.match(new RegExp(`^ctx\\.([a-zA-Z_$][a-zA-Z0-9_$]*)(?:\\.(${segment}(?:\\.${segment})*))?$`));
+  if (!match) return null;
+  return {
+    methodCall: false,
+    path: match[2] || void 0,
+    unsupportedDynamicPath: false,
+    varName: match[1]
+  };
+}
+__name(parseDotOnlyCtxReference, "parseDotOnlyCtxReference");
+function parseCtxReference(input, start) {
+  if (input.slice(start, start + 3) !== "ctx") return null;
+  if (isIdentifierPart(input[start - 1]) || isIdentifierPart(input[start + 3])) return null;
+  if (isGroupedCtxReference(input, start)) {
+    return {
+      next: start + 3,
+      reference: {
+        methodCall: false,
+        unsupportedDynamicPath: true,
+        varName: ""
       }
-    } else if (Array.isArray(src)) {
-      src.forEach(visit);
-    } else if (src && typeof src === "object") {
-      Object.values(src).forEach(visit);
+    };
+  }
+  const rootAccess = readAccess(input, start + 3);
+  if (!rootAccess) return null;
+  if (rootAccess.dynamic) {
+    return {
+      next: start + 3,
+      reference: {
+        methodCall: false,
+        unsupportedDynamicPath: true,
+        varName: ""
+      }
+    };
+  }
+  if (rootAccess.kind !== "property") {
+    return null;
+  }
+  const segments = [];
+  let next = rootAccess.next;
+  let methodCall = false;
+  let unsupportedDynamicPath = false;
+  while (next < input.length) {
+    const accessStart = skipPostfix(input, next);
+    if ((input[accessStart] === "(" || input.startsWith("?.(", accessStart)) && !segments.length) {
+      methodCall = true;
+      next = accessStart;
+      break;
     }
-  }, "visit");
-  visit(template);
-  return result;
+    const access = readAccess(input, next);
+    if (!access) {
+      next = accessStart;
+      if (input[accessStart] === "[" || input[accessStart] === "." || input.startsWith("?.", accessStart)) {
+        unsupportedDynamicPath = true;
+      }
+      break;
+    }
+    if (access.dynamic) {
+      unsupportedDynamicPath = true;
+      next = accessStart;
+      break;
+    }
+    appendPathSegment(segments, access.kind, access.value);
+    next = access.next;
+  }
+  const path = segments.join(".");
+  return {
+    next: Math.max(next, rootAccess.next),
+    reference: {
+      methodCall,
+      path: path || void 0,
+      unsupportedDynamicPath: unsupportedDynamicPath || hasGroupedContinuation(input, next),
+      varName: rootAccess.value
+    }
+  };
 }
-__name(extractUsedVariableNames, "extractUsedVariableNames");
-function extractUsedVariablePaths(template) {
+__name(parseCtxReference, "parseCtxReference");
+function collectCtxReferences(expr) {
+  const dotOnly = parseDotOnlyCtxReference(expr);
+  if (dotOnly) return [dotOnly];
+  const references = [];
+  for (let index = 0; index < expr.length; index += 1) {
+    if (expr.slice(index, index + 3) !== "ctx") continue;
+    const parsed = parseCtxReference(expr, index);
+    if (!parsed) continue;
+    references.push(parsed.reference);
+    index = Math.max(index, parsed.next - 1);
+  }
+  return references;
+}
+__name(collectCtxReferences, "collectCtxReferences");
+function addUsagePath(usage, varName, path, methodCall) {
+  usage[varName] = usage[varName] || [];
+  if (path) {
+    usage[varName].push(path);
+  } else if (methodCall && !usage[varName].includes("")) {
+    usage[varName].push("");
+  }
+}
+__name(addUsagePath, "addUsagePath");
+function extractVariableUsage(template) {
   const usage = {};
+  let unsupportedDynamicPath = false;
+  const visitExpression = /* @__PURE__ */ __name((expr) => {
+    for (const reference of collectCtxReferences(expr)) {
+      if (reference.unsupportedDynamicPath) {
+        unsupportedDynamicPath = true;
+        continue;
+      }
+      if (!reference.varName) continue;
+      addUsagePath(usage, reference.varName, reference.path, reference.methodCall);
+    }
+  }, "visitExpression");
   const visit = /* @__PURE__ */ __name((src) => {
     if (typeof src === "string") {
       const regex = /\{\{\s*([^}]+?)\s*\}\}/g;
-      let m;
-      while ((m = regex.exec(src)) !== null) {
-        const expr = m[1];
-        const pathRegex = /ctx\.([a-zA-Z_$][a-zA-Z0-9_$]*)([^\s)]*)/g;
-        let pm;
-        while ((pm = pathRegex.exec(expr)) !== null) {
-          const varName = pm[1];
-          const after = pm[2] || "";
-          usage[varName] = usage[varName] || [];
-          if (after.startsWith(".")) {
-            usage[varName].push(after.slice(1));
-          } else if (after.startsWith("[")) {
-            const mm = after.match(/^\[\s*(["'])\s*([^'"\]]+)\s*\1\s*\](.*)$/);
-            if (mm) {
-              const first = mm[2];
-              const rest = mm[3] || "";
-              usage[varName].push(`${first}${rest}`);
-            } else {
-              const mn = after.match(/^\[(\d+)\](.*)$/);
-              if (mn) {
-                const idx = mn[1];
-                const rest = mn[2] || "";
-                usage[varName].push(`[${idx}]${rest}`);
-              }
-            }
-          } else if (after.startsWith("(")) {
-            if (!usage[varName].length) usage[varName].push("");
-          }
-        }
-        const bracketVarRegex = /ctx\[\s*(["'])\s*([a-zA-Z_$][a-zA-Z0-9_$]*)\s*\1\s*\]([^\s)]*)/g;
-        let bm;
-        while ((bm = bracketVarRegex.exec(expr)) !== null) {
-          const varName = bm[2];
-          const after = bm[3] || "";
-          usage[varName] = usage[varName] || [];
-          if (after.startsWith(".")) {
-            usage[varName].push(after.slice(1));
-          } else if (after.startsWith("[")) {
-            const mm = after.match(/^\[\s*(["'])\s*([^'"\]]+)\s*\1\s*\](.*)$/);
-            if (mm) {
-              const first = mm[2];
-              const rest = mm[3] || "";
-              usage[varName].push(`${first}${rest}`);
-            } else {
-              const mn = after.match(/^\[(\d+)\](.*)$/);
-              if (mn) {
-                const idx = mn[1];
-                const rest = mn[2] || "";
-                usage[varName].push(`[${idx}]${rest}`);
-              }
-            }
-          } else if (after.startsWith("(")) {
-            if (!usage[varName].length) usage[varName].push("");
-          }
-        }
+      let match;
+      while ((match = regex.exec(src)) !== null) {
+        visitExpression(match[1]);
       }
-    } else if (Array.isArray(src)) {
+      return;
+    }
+    if (Array.isArray(src)) {
       src.forEach(visit);
-    } else if (src && typeof src === "object") {
+      return;
+    }
+    if (isObject(src)) {
       Object.values(src).forEach(visit);
     }
   }, "visit");
   visit(template);
-  return usage;
+  return { unsupportedDynamicPath, usage };
+}
+__name(extractVariableUsage, "extractVariableUsage");
+function extractUsedVariableNames(template) {
+  return new Set(Object.keys(extractVariableUsage(template).usage));
+}
+__name(extractUsedVariableNames, "extractUsedVariableNames");
+function extractUsedVariablePaths(template) {
+  return extractVariableUsage(template).usage;
 }
 __name(extractUsedVariablePaths, "extractUsedVariablePaths");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   extractUsedVariableNames,
-  extractUsedVariablePaths
+  extractUsedVariablePaths,
+  extractVariableUsage
 });

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@nocobase/shared",
-  "version": "3.0.0-alpha.1",
+  "version": "3.0.0-alpha.12",
   "main": "lib/index.js",
   "types": "./lib/index.d.ts",
   "license": "Apache-2.0",
-  "gitHead": "22d8be8ece179cfa5c8a4ebb2c896c92bd418e03"
+  "gitHead": "2ba035885741a9977d76bbabf8f2caf44b199139"
 }

package/src/index.ts

@@ -8,4 +8,5 @@
  */
 
 export * from './getValuesByPath';
+export * from './ui-operation';
 export * from './variable-usage';

package/src/ui-operation.ts

@@ -0,0 +1,99 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+export const UI_OPERATION_QUERY_KEY = '_operation_';
+export const UI_OPERATION_VERSION = 1;
+export const MAX_UI_OPERATION_ENCODED_LENGTH = 8 * 1024;
+
+export interface UIOperation<
+  TOperationId extends string = string,
+  TParams extends Record<string, unknown> = Record<string, unknown>,
+> {
+  v: typeof UI_OPERATION_VERSION;
+  operationId: TOperationId;
+  params?: TParams;
+}
+
+export interface UIOperationCodec {
+  encode(value: string): string;
+  decode(value: string): string | undefined;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return false;
+  }
+
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+export function isUIOperation(value: unknown): value is UIOperation {
+  if (
+    !isPlainObject(value) ||
+    value.v !== UI_OPERATION_VERSION ||
+    typeof value.operationId !== 'string' ||
+    !value.operationId
+  ) {
+    return false;
+  }
+
+  return value.params === undefined || isPlainObject(value.params);
+}
+
+export function encodeUIOperation(operation: UIOperation, codec: UIOperationCodec): string {
+  if (!isUIOperation(operation)) {
+    throw new TypeError('Invalid UI operation.');
+  }
+
+  const encoded = codec.encode(JSON.stringify(operation));
+  if (encoded.length > MAX_UI_OPERATION_ENCODED_LENGTH) {
+    throw new RangeError(`UI operation exceeds the ${MAX_UI_OPERATION_ENCODED_LENGTH}-byte encoded length limit.`);
+  }
+
+  return encoded;
+}
+
+export function decodeUIOperation(encoded: string, codec: UIOperationCodec): UIOperation | undefined {
+  if (encoded.length > MAX_UI_OPERATION_ENCODED_LENGTH) {
+    return undefined;
+  }
+
+  try {
+    const decoded = codec.decode(encoded);
+    if (decoded === undefined) {
+      return undefined;
+    }
+
+    const parsed: unknown = JSON.parse(decoded);
+    return isUIOperation(parsed) ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export function parseUIOperation(search: string, codec: UIOperationCodec): UIOperation | undefined {
+  try {
+    const values = new URLSearchParams(search).getAll(UI_OPERATION_QUERY_KEY);
+    if (values.length !== 1) {
+      return undefined;
+    }
+
+    return decodeUIOperation(values[0], codec);
+  } catch {
+    return undefined;
+  }
+}
+
+export function removeUIOperation(search: string): string {
+  const params = new URLSearchParams(search);
+  params.delete(UI_OPERATION_QUERY_KEY);
+  const remaining = params.toString();
+  return remaining ? `?${remaining}` : '';
+}

package/src/variable-usage.ts

@@ -10,41 +10,316 @@
 // 轻量模板类型定义：与前后端均可复用
 export type JSONValue = string | { [key: string]: JSONValue } | JSONValue[];
 
+export type VariableUsageExtractionResult = {
+  unsupportedDynamicPath: boolean;
+  usage: Record<string, string[]>;
+};
+
+type CtxReference = {
+  methodCall: boolean;
+  path?: string;
+  unsupportedDynamicPath: boolean;
+  varName: string;
+};
+
+function isObject(value: unknown): value is Record<string, JSONValue> {
+  return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isIdentifierStart(char: string | undefined) {
+  return !!char && /[a-zA-Z_$]/.test(char);
+}
+
+function isIdentifierPart(char: string | undefined) {
+  return !!char && /[a-zA-Z0-9_$]/.test(char);
+}
+
+function skipSpaces(input: string, index: number) {
+  let next = index;
+  while (/\s/.test(input[next] || '')) next += 1;
+  return next;
+}
+
+function skipPostfix(input: string, index: number) {
+  let next = skipSpaces(input, index);
+  while (input[next] === '!') {
+    next = skipSpaces(input, next + 1);
+  }
+  return next;
+}
+
+function previousNonSpaceIndex(input: string, index: number) {
+  let next = index;
+  while (next >= 0 && /\s/.test(input[next] || '')) next -= 1;
+  return next;
+}
+
+function isGroupedCtxReference(input: string, start: number) {
+  const openParenIndex = previousNonSpaceIndex(input, start - 1);
+  if (input[openParenIndex] !== '(') return false;
+
+  const beforeOpenParenIndex = previousNonSpaceIndex(input, openParenIndex - 1);
+  if (beforeOpenParenIndex < 0) return true;
+
+  const beforeOpenParen = input[beforeOpenParenIndex];
+  return !isIdentifierPart(beforeOpenParen) && beforeOpenParen !== ')' && beforeOpenParen !== ']';
+}
+
+function hasGroupedContinuation(input: string, index: number) {
+  const closeParenIndex = skipSpaces(input, index);
+  if (input[closeParenIndex] !== ')') return false;
+
+  const continuationIndex = skipSpaces(input, closeParenIndex + 1);
+  return (
+    input[continuationIndex] === '.' || input[continuationIndex] === '[' || input.startsWith('?.', continuationIndex)
+  );
+}
+
+function readIdentifier(input: string, index: number): { next: number; value: string } | null {
+  if (!isIdentifierStart(input[index])) return null;
+  let next = index + 1;
+  while (isIdentifierPart(input[next])) next += 1;
+  return { value: input.slice(index, next), next };
+}
+
+function readNumber(input: string, index: number): { next: number; value: string } | null {
+  const match = input.slice(index).match(/^\d+/);
+  return match ? { value: match[0], next: index + match[0].length } : null;
+}
+
+function readQuotedProperty(input: string, index: number): { next: number; value: string } | null {
+  const quote = input[index];
+  if (quote !== '"' && quote !== "'") return null;
+  let next = index + 1;
+  let value = '';
+  while (next < input.length) {
+    const char = input[next];
+    if (char === '\\') {
+      value += input.slice(next, next + 2);
+      next += 2;
+      continue;
+    }
+    if (char === quote) {
+      return { value, next: next + 1 };
+    }
+    value += char;
+    next += 1;
+  }
+  return null;
+}
+
+function readBracketAccess(input: string, index: number) {
+  let next = skipSpaces(input, index + 1);
+  const quoted = readQuotedProperty(input, next);
+  if (quoted) {
+    next = skipSpaces(input, quoted.next);
+    if (input[next] !== ']') return { dynamic: true as const };
+    return { dynamic: false as const, kind: 'property' as const, next: next + 1, value: quoted.value };
+  }
+
+  const number = readNumber(input, next);
+  if (number) {
+    next = skipSpaces(input, number.next);
+    if (input[next] !== ']') return { dynamic: true as const };
+    return { dynamic: false as const, kind: 'index' as const, next: next + 1, value: number.value };
+  }
+
+  return { dynamic: true as const };
+}
+
+function appendPathSegment(segments: string[], kind: 'property' | 'index', value: string) {
+  if (kind === 'property') {
+    segments.push(value);
+    return;
+  }
+  if (segments.length) {
+    segments[segments.length - 1] = `${segments[segments.length - 1]}[${value}]`;
+    return;
+  }
+  segments.push(`[${value}]`);
+}
+
+function readAccess(input: string, index: number) {
+  const next = skipPostfix(input, index);
+  if (input[next] === '[') {
+    return readBracketAccess(input, next);
+  }
+  if (input.startsWith('?.', next)) {
+    const propertyStart = skipSpaces(input, next + 2);
+    if (input[propertyStart] === '[') {
+      return readBracketAccess(input, propertyStart);
+    }
+    const identifier = readIdentifier(input, propertyStart) || readNumber(input, propertyStart);
+    return identifier
+      ? { dynamic: false as const, kind: 'property' as const, next: identifier.next, value: identifier.value }
+      : null;
+  }
+  if (input[next] === '.') {
+    const propertyStart = skipSpaces(input, next + 1);
+    const identifier = readIdentifier(input, propertyStart) || readNumber(input, propertyStart);
+    return identifier
+      ? { dynamic: false as const, kind: 'property' as const, next: identifier.next, value: identifier.value }
+      : null;
+  }
+  return null;
+}
+
+function parseDotOnlyCtxReference(expr: string): CtxReference | null {
+  const trimmed = expr.trim();
+  const segment = '(?:[a-zA-Z_$][a-zA-Z0-9_$-]*|\\d+)';
+  const match = trimmed.match(new RegExp(`^ctx\\.([a-zA-Z_$][a-zA-Z0-9_$]*)(?:\\.(${segment}(?:\\.${segment})*))?$`));
+  if (!match) return null;
+  return {
+    methodCall: false,
+    path: match[2] || undefined,
+    unsupportedDynamicPath: false,
+    varName: match[1],
+  };
+}
+
+function parseCtxReference(input: string, start: number): { next: number; reference: CtxReference } | null {
+  if (input.slice(start, start + 3) !== 'ctx') return null;
+  if (isIdentifierPart(input[start - 1]) || isIdentifierPart(input[start + 3])) return null;
+
+  if (isGroupedCtxReference(input, start)) {
+    return {
+      next: start + 3,
+      reference: {
+        methodCall: false,
+        unsupportedDynamicPath: true,
+        varName: '',
+      },
+    };
+  }
+
+  const rootAccess = readAccess(input, start + 3);
+  if (!rootAccess) return null;
+  if (rootAccess.dynamic) {
+    return {
+      next: start + 3,
+      reference: {
+        methodCall: false,
+        unsupportedDynamicPath: true,
+        varName: '',
+      },
+    };
+  }
+  if (rootAccess.kind !== 'property') {
+    return null;
+  }
+
+  const segments: string[] = [];
+  let next = rootAccess.next;
+  let methodCall = false;
+  let unsupportedDynamicPath = false;
+
+  while (next < input.length) {
+    const accessStart = skipPostfix(input, next);
+    if ((input[accessStart] === '(' || input.startsWith('?.(', accessStart)) && !segments.length) {
+      methodCall = true;
+      next = accessStart;
+      break;
+    }
+
+    const access = readAccess(input, next);
+    if (!access) {
+      next = accessStart;
+      if (input[accessStart] === '[' || input[accessStart] === '.' || input.startsWith('?.', accessStart)) {
+        unsupportedDynamicPath = true;
+      }
+      break;
+    }
+    if (access.dynamic) {
+      unsupportedDynamicPath = true;
+      next = accessStart;
+      break;
+    }
+    appendPathSegment(segments, access.kind, access.value);
+    next = access.next;
+  }
+
+  const path = segments.join('.');
+  return {
+    next: Math.max(next, rootAccess.next),
+    reference: {
+      methodCall,
+      path: path || undefined,
+      unsupportedDynamicPath: unsupportedDynamicPath || hasGroupedContinuation(input, next),
+      varName: rootAccess.value,
+    },
+  };
+}
+
+function collectCtxReferences(expr: string): CtxReference[] {
+  const dotOnly = parseDotOnlyCtxReference(expr);
+  if (dotOnly) return [dotOnly];
+
+  const references: CtxReference[] = [];
+  for (let index = 0; index < expr.length; index += 1) {
+    if (expr.slice(index, index + 3) !== 'ctx') continue;
+    const parsed = parseCtxReference(expr, index);
+    if (!parsed) continue;
+    references.push(parsed.reference);
+    index = Math.max(index, parsed.next - 1);
+  }
+  return references;
+}
+
+function addUsagePath(usage: Record<string, string[]>, varName: string, path?: string, methodCall?: boolean) {
+  usage[varName] = usage[varName] || [];
+  if (path) {
+    usage[varName].push(path);
+  } else if (methodCall && !usage[varName].includes('')) {
+    usage[varName].push('');
+  }
+}
+
 /**
- * 提取模板中使用到的 ctx 顶层变量名集合。
- * - 支持点语法与顶层括号变量：ctx.user / ctx["user"]
+ * 提取模板中的 ctx 使用情况。该函数只做静态扫描，不执行表达式。
  */
-export function extractUsedVariableNames(template: JSONValue): Set<string> {
-  const result = new Set<string>();
+export function extractVariableUsage(template: JSONValue): VariableUsageExtractionResult {
+  const usage: Record<string, string[]> = {};
+  let unsupportedDynamicPath = false;
 
-  const visit = (src: any) => {
+  const visitExpression = (expr: string) => {
+    for (const reference of collectCtxReferences(expr)) {
+      if (reference.unsupportedDynamicPath) {
+        unsupportedDynamicPath = true;
+        continue;
+      }
+      if (!reference.varName) continue;
+      addUsagePath(usage, reference.varName, reference.path, reference.methodCall);
+    }
+  };
+
+  const visit = (src: JSONValue) => {
     if (typeof src === 'string') {
       const regex = /\{\{\s*([^}]+?)\s*\}\}/g;
-      let m: RegExpExecArray | null;
-      while ((m = regex.exec(src)) !== null) {
-        const expr = m[1];
-        // ctx.<var>
-        const pathRegex = /ctx\.([a-zA-Z_$][a-zA-Z0-9_$]*)/g;
-        let pm: RegExpExecArray | null;
-        while ((pm = pathRegex.exec(expr)) !== null) {
-          result.add(pm[1]);
-        }
-        // ctx["var"] or ctx['var']
-        const bracketVarRegex = /ctx\[\s*(["'])\s*([a-zA-Z_$][a-zA-Z0-9_$]*)\s*\1\s*\]/g;
-        let bm: RegExpExecArray | null;
-        while ((bm = bracketVarRegex.exec(expr)) !== null) {
-          result.add(bm[2]);
-        }
+      let match: RegExpExecArray | null;
+      while ((match = regex.exec(src)) !== null) {
+        visitExpression(match[1]);
       }
-    } else if (Array.isArray(src)) {
+      return;
+    }
+    if (Array.isArray(src)) {
       src.forEach(visit);
-    } else if (src && typeof src === 'object') {
+      return;
+    }
+    if (isObject(src)) {
       Object.values(src).forEach(visit);
     }
   };
 
   visit(template);
-  return result;
+  return { unsupportedDynamicPath, usage };
+}
+
+/**
+ * 提取模板中使用到的 ctx 顶层变量名集合。
+ * - 支持点语法与顶层括号变量：ctx.user / ctx["user"]
+ */
+export function extractUsedVariableNames(template: JSONValue): Set<string> {
+  return new Set(Object.keys(extractVariableUsage(template).usage));
 }
 
 /**
@@ -54,79 +329,5 @@ export function extractUsedVariableNames(template: JSONValue): Set<string> {
  * - 方法调用：记录空字符串以触发服务端 attach（例如 ctx.twice(21) => { twice: [''] }）
  */
 export function extractUsedVariablePaths(template: JSONValue): Record<string, string[]> {
-  const usage: Record<string, string[]> = {};
-
-  const visit = (src: any) => {
-    if (typeof src === 'string') {
-      const regex = /\{\{\s*([^}]+?)\s*\}\}/g;
-      let m: RegExpExecArray | null;
-      while ((m = regex.exec(src)) !== null) {
-        const expr = m[1];
-
-        // 点语法：ctx.varName[...]
-        const pathRegex = /ctx\.([a-zA-Z_$][a-zA-Z0-9_$]*)([^\s)]*)/g;
-        let pm: RegExpExecArray | null;
-        while ((pm = pathRegex.exec(expr)) !== null) {
-          const varName = pm[1];
-          const after = pm[2] || '';
-          usage[varName] = usage[varName] || [];
-          if (after.startsWith('.')) {
-            usage[varName].push(after.slice(1));
-          } else if (after.startsWith('[')) {
-            // 首段括号键或数字索引
-            const mm = after.match(/^\[\s*(["'])\s*([^'"\]]+)\s*\1\s*\](.*)$/);
-            if (mm) {
-              const first = mm[2];
-              const rest = mm[3] || '';
-              usage[varName].push(`${first}${rest}`);
-            } else {
-              const mn = after.match(/^\[(\d+)\](.*)$/);
-              if (mn) {
-                const idx = mn[1];
-                const rest = mn[2] || '';
-                usage[varName].push(`[${idx}]${rest}`);
-              }
-            }
-          } else if (after.startsWith('(')) {
-            if (!usage[varName].length) usage[varName].push('');
-          }
-        }
-
-        // 顶层括号变量：ctx["varName"]...
-        const bracketVarRegex = /ctx\[\s*(["'])\s*([a-zA-Z_$][a-zA-Z0-9_$]*)\s*\1\s*\]([^\s)]*)/g;
-        let bm: RegExpExecArray | null;
-        while ((bm = bracketVarRegex.exec(expr)) !== null) {
-          const varName = bm[2];
-          const after = bm[3] || '';
-          usage[varName] = usage[varName] || [];
-          if (after.startsWith('.')) {
-            usage[varName].push(after.slice(1));
-          } else if (after.startsWith('[')) {
-            const mm = after.match(/^\[\s*(["'])\s*([^'"\]]+)\s*\1\s*\](.*)$/);
-            if (mm) {
-              const first = mm[2];
-              const rest = mm[3] || '';
-              usage[varName].push(`${first}${rest}`);
-            } else {
-              const mn = after.match(/^\[(\d+)\](.*)$/);
-              if (mn) {
-                const idx = mn[1];
-                const rest = mn[2] || '';
-                usage[varName].push(`[${idx}]${rest}`);
-              }
-            }
-          } else if (after.startsWith('(')) {
-            if (!usage[varName].length) usage[varName].push('');
-          }
-        }
-      }
-    } else if (Array.isArray(src)) {
-      src.forEach(visit);
-    } else if (src && typeof src === 'object') {
-      Object.values(src).forEach(visit);
-    }
-  };
-
-  visit(template);
-  return usage;
+  return extractVariableUsage(template).usage;
 }