@bsm-form/core 0.40.0 → 0.41.0

package/dist/index.cjs

@@ -27,25 +27,86 @@ __export(index_exports, {
   adaptDisplay: () => adaptDisplay,
   adaptField: () => adaptField,
   adaptLayout: () => adaptLayout,
+  collectFormEnvReferences: () => collectFormEnvReferences,
   compileSchema: () => compileSchema,
   conditions: () => conditions,
   createFormEngineEnvironment: () => createFormEngineEnvironment,
   createRuntimeNode: () => createRuntimeNode,
   formatTagSourceValue: () => formatTagSourceValue,
   isThenable: () => isThenable,
+  remapFormEnvReferences: () => remapFormEnvReferences,
+  resolveFormEnv: () => resolveFormEnv,
   resolveLoadingProp: () => resolveLoadingProp,
   resolveTagValueMapping: () => resolveTagValueMapping,
   runConditionEngine: () => runConditionEngine,
   tagMapKey: () => tagMapKey,
   traverseNode: () => traverseNode,
   validateApiUrlTemplate: () => validateApiUrlTemplate,
+  validateEnvBaseUrl: () => validateEnvBaseUrl,
+  validateEnvDefinitions: () => validateEnvDefinitions,
   validateField: () => validateField,
+  validateFormEnvReferences: () => validateFormEnvReferences,
   validateSchema: () => validateSchema,
   validation: () => validation,
   validationRegistry: () => validationRegistry
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/utils/form-env.ts
+function validateEnvBaseUrl(value) {
+  if (!value || /[\\\s?#]/.test(value) || value.startsWith("//")) throw new Error("Base URL cannot contain whitespace, query, fragment, or backslashes");
+  if (value.startsWith("/")) return;
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error("Expected an http(s) URL or path starting with /");
+  }
+  if (!["http:", "https:"].includes(url.protocol) || url.username || url.password) throw new Error("Base URL must use http(s) without credentials");
+}
+function validateValue(name, type, value) {
+  if (typeof value !== (type === "url" ? "string" : type) || typeof value === "number" && !Number.isFinite(value)) throw new Error(`env.${name}: expected ${String(type)}`);
+  if (type === "url") {
+    try {
+      validateEnvBaseUrl(value);
+    } catch (error) {
+      throw new Error(`env.${name}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+}
+function validateEnvDefinitions(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("Environment definitions must be an object");
+  for (const [name, entry] of Object.entries(value)) {
+    if (!/^[A-Za-z_]+$/.test(name) || ["__proto__", "prototype", "constructor"].includes(name)) throw new Error(`Invalid environment variable name: ${name}`);
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) throw new Error(`env.${name}: expected a definition`);
+    const definition = entry;
+    if (!["string", "number", "boolean", "url"].includes(String(definition.type))) throw new Error(`env.${name}: invalid type`);
+    for (const key of Object.keys(definition)) if (!["type", "label", "description", "default", "required", "allowOverride"].includes(key)) throw new Error(`env.${name}: unknown property ${key}`);
+    for (const key of ["required", "allowOverride"]) if (definition[key] !== void 0 && typeof definition[key] !== "boolean") throw new Error(`env.${name}.${key}: expected boolean`);
+    for (const key of ["label", "description"]) if (definition[key] !== void 0 && typeof definition[key] !== "string") throw new Error(`env.${name}.${key}: expected string`);
+    if (Object.hasOwn(definition, "default")) validateValue(name, definition.type, definition.default);
+  }
+}
+function resolveFormEnv(config = {}, requireValues = true) {
+  const definitions = config.definitions ?? {};
+  const overrides = config.overrides ?? {};
+  validateEnvDefinitions(definitions);
+  if (typeof overrides !== "object" || Array.isArray(overrides)) throw new Error("Environment overrides must be an object");
+  for (const name of Object.keys(overrides)) {
+    if (!Object.hasOwn(definitions, name)) throw new Error(`env.${name}: unknown override`);
+    if (definitions[name]?.allowOverride === false) throw new Error(`env.${name}: overrides are disabled`);
+  }
+  const values = {};
+  for (const [name, definition] of Object.entries(definitions)) {
+    const provided = Object.hasOwn(overrides, name);
+    const value = provided ? overrides[name] : definition.default;
+    if (provided || value !== void 0) validateValue(name, definition.type, value);
+    if (requireValues && definition.required && (value === void 0 || value === "")) throw new Error(`env.${name}: required value is missing`);
+    if (value !== void 0) values[name] = value;
+  }
+  return Object.freeze(values);
+}
+
 // src/utils/get-path.ts
 function pathSegments(path) {
   const segments = [];
@@ -93,6 +154,8 @@ function getPath(obj, path) {
 
 // src/utils/scope-path.ts
 function resolveScopedPath(ctx, path) {
+  if (path === "env") return ctx.env ?? {};
+  if (path.startsWith("env.")) return getPath(ctx.env ?? {}, path.slice(4));
   if (path === "$values" || path === "values") {
     return ctx.values;
   }
@@ -120,7 +183,7 @@ function resolveScopedPath(ctx, path) {
   return getPath(ctx.values, path);
 }
 function isExplicitScopedPath(path) {
-  return path === "$values" || path === "values" || path === "$resources" || path === "resources" || path === "$row" || path === "row" || path === "$item" || path === "item" || path.startsWith("values.") || path.startsWith("resources.") || path.startsWith("row.") || path.startsWith("item.");
+  return path === "env" || path.startsWith("env.") || path === "$values" || path === "values" || path === "$resources" || path === "resources" || path === "$row" || path === "row" || path === "$item" || path === "item" || path.startsWith("values.") || path.startsWith("resources.") || path.startsWith("row.") || path.startsWith("item.");
 }
 function resolvePathStringsInData(value, ctx) {
   if (typeof value === "string") {
@@ -140,7 +203,7 @@ function resolvePathStringsInData(value, ctx) {
 }
 
 // src/utils/url-template.ts
-var pathPattern = /^(values|resources)\.[A-Za-z_$][\w$]*(?:(?:\.(?:[A-Za-z_$][\w$]*|\d+))|(?:\[\d+\]))*$/;
+var pathPattern = /^(values|resources|env)\.[A-Za-z_$][\w$]*(?:(?:\.(?:[A-Za-z_$][\w$]*|\d+))|(?:\[\d+\]))*$/;
 function placeholders(url) {
   const result = [];
   let cursor = 0;
@@ -151,10 +214,10 @@ function placeholders(url) {
     if (close < 0) throw new Error("API URL template has an unclosed placeholder");
     const path = url.slice(start + 2, close).trim();
     if (!pathPattern.test(path)) {
-      throw new Error(`Invalid API URL placeholder: ${path}. Use a values.* or resources.* data path`);
+      throw new Error(`Invalid API URL placeholder: ${path}. Use a values.*, resources.*, or env.* data path`);
     }
     const origin = url.match(/^(?:[A-Za-z][A-Za-z0-9+.-]*:)?\/\/[^/?#]*/)?.[0];
-    if (start === 0 || origin && start < origin.length) {
+    if (start === 0 && !path.startsWith("env.") || origin && start < origin.length) {
       throw new Error("API URL placeholders cannot replace the service origin; use a static base URL");
     }
     result.push({ start, end: close + 1, path });
@@ -166,7 +229,7 @@ function validateApiUrlTemplate(url) {
   if (!url.trim()) throw new Error("API URL must not be empty");
   placeholders(url);
 }
-function resolveApiUrlTemplate(url, context) {
+function resolveApiUrlTemplate(url, context, definitions = {}) {
   validateApiUrlTemplate(url);
   let result = "";
   let cursor = 0;
@@ -178,7 +241,17 @@ function resolveApiUrlTemplate(url, context) {
     if (value === "." || value === "..") {
       throw new Error(`API URL placeholder ${placeholder.path} cannot be a dot segment`);
     }
-    result += url.slice(cursor, placeholder.start) + encodeURIComponent(String(value));
+    if (placeholder.start === 0 && placeholder.path.startsWith("env.")) {
+      if (definitions[placeholder.path.slice(4)]?.type !== "url" || typeof value !== "string") {
+        throw new Error(`${placeholder.path}: only an env variable of type url can supply a base URL`);
+      }
+      validateEnvBaseUrl(value);
+      const suffix = url.slice(placeholder.end);
+      if (suffix && !suffix.startsWith("/")) throw new Error("Base URL placeholder must be followed by / or end of URL");
+      result += suffix.startsWith("/") ? value.replace(/\/+$/, "") : value;
+    } else {
+      result += url.slice(cursor, placeholder.start) + encodeURIComponent(String(value));
+    }
     cursor = placeholder.end;
   }
   return result + url.slice(cursor);
@@ -1602,6 +1675,7 @@ function validateDrawerStepReferences(context) {
 }
 function validateStepConditionReferences(context) {
   context.stepConditionReferences.forEach(({ path, field }) => {
+    if (field.startsWith("env.")) return;
     if ((0, import_schema.isReservedConditionField)(field)) {
       if ((0, import_schema.isPendingActionConditionField)(field)) {
         const actionId = (0, import_schema.pendingActionIdFromField)(field);
@@ -1762,6 +1836,7 @@ var validationRegistry = {
 // src/engine/environment.ts
 function createFormEngineEnvironment(overrides = {}) {
   return {
+    env: overrides.env ?? Object.freeze({}),
     request: overrides.request ?? defaultRequest,
     log: overrides.log ?? defaultLog,
     navigate: overrides.navigate ?? defaultNavigate,
@@ -1831,6 +1906,7 @@ function runInvokeValidator(rule, options) {
   const ctx = {
     values: options?.values ?? {},
     resources: options?.resources ?? {},
+    env: options?.env ?? options?.environment?.env,
     ...options?.row !== void 0 ? { row: options.row } : {},
     ...options?.item !== void 0 ? { item: options.item } : {}
   };
@@ -1926,6 +2002,7 @@ function evaluateCondition(condition, values, state, options) {
   }
   const target = resolveConditionTarget(condition.field, values, state, {
     resources: options?.resources,
+    env: options?.env ?? options?.environment?.env,
     ...options?.row !== void 0 ? { row: options.row } : {},
     ...options?.item !== void 0 ? { item: options.item } : {}
   });
@@ -1972,6 +2049,7 @@ function evaluateInvokeCondition(name, values, options) {
   const ctx = {
     values,
     resources: options?.resources ?? {},
+    env: options?.env ?? options?.environment?.env,
     ...options?.row !== void 0 ? { row: options.row } : {},
     ...options?.item !== void 0 ? { item: options.item } : {}
   };
@@ -2026,6 +2104,7 @@ function resolveConditionTarget(field, values, state, options) {
     {
       values,
       resources: options?.resources ?? {},
+      env: options?.env,
       ...options?.row !== void 0 ? { row: options.row } : {},
       ...options?.item !== void 0 ? { item: options.item } : {}
     },
@@ -2319,7 +2398,7 @@ var DependencyGraph = class {
     return ordered;
   }
   extractDependencies(conditions2) {
-    return conditions2.filter(import_schema4.isFieldCondition).map((condition) => condition.field).filter((field) => !(0, import_schema4.isReservedConditionField)(field));
+    return conditions2.filter(import_schema4.isFieldCondition).map((condition) => condition.field).filter((field) => !(0, import_schema4.isReservedConditionField)(field) && !field.startsWith("env."));
   }
   clear() {
     this.forward.clear();
@@ -2341,10 +2420,52 @@ var EventBus = class {
   }
 };
 
+// src/utils/env-references.ts
+var pathKeys = /* @__PURE__ */ new Set(["from", "source", "field", "path", "bodyFrom", "queryFrom"]);
+function visit(value, path, key, data, transform) {
+  if (typeof value === "string") {
+    if (key === "url") return transform(value, path, true);
+    if ((pathKeys.has(key) || path.endsWith(".bind.value") || data) && /^env\.[A-Za-z_]/.test(value)) return transform(value, path, false);
+    return value;
+  }
+  if (Array.isArray(value)) return value.map((item, index) => visit(item, `${path}[${index}]`, key, data, transform));
+  if (value && typeof value === "object") return Object.fromEntries(Object.entries(value).map(([childKey, child]) => [
+    childKey,
+    visit(child, `${path}.${childKey}`, childKey, data || childKey === "body" || childKey === "query", transform)
+  ]));
+  return value;
+}
+function collectFormEnvReferences(schema) {
+  const references = [];
+  visit(schema, "schema", "", false, (value, path, template) => {
+    if (template) {
+      for (const match of value.matchAll(/\$\{\s*env\.([A-Za-z_][A-Za-z0-9_]*)\s*\}/g)) {
+        references.push({ name: match[1], path });
+      }
+    } else references.push({ name: value.slice(4).split(/[.[]/)[0], path });
+    return value;
+  });
+  return references;
+}
+function validateFormEnvReferences(schema, definitions = {}) {
+  for (const reference of collectFormEnvReferences(schema)) {
+    if (!Object.hasOwn(definitions, reference.name)) throw new Error(`${reference.path}: undefined environment variable env.${reference.name}`);
+  }
+}
+function remapFormEnvReferences(schema, previous, next) {
+  return visit(schema, "schema", "", false, (value, _path, template) => {
+    if (template) return value.replace(
+      /\$\{\s*env\.([A-Za-z_][A-Za-z0-9_]*)\s*\}/g,
+      (original, name) => name === previous ? "${env." + next + "}" : original
+    );
+    return value === `env.${previous}` ? `env.${next}` : value;
+  });
+}
+
 // src/pipeline/run-conditions.ts
 function runConditions(ctx) {
-  visit(ctx.tree, true);
-  function visit(node, parentVisible) {
+  visit2(ctx.tree, true);
+  function visit2(node, parentVisible) {
     const schema = node.schema;
     const hasVisibilityConditions = schema.kind === "field" || schema.kind === "display" || schema.kind === "action" || schema.kind === "layout" && schema.type === "step";
     if (!parentVisible) {
@@ -2362,7 +2483,7 @@ function runConditions(ctx) {
     }
     node.state.disabled = evaluateDisabled(schema, ctx);
     const childrenVisible = node.state.visible && !(schema.kind === "layout" && (schema.type === "dialog" || schema.type === "drawer") && node.state.open !== true);
-    node.children.forEach((child) => visit(child, childrenVisible));
+    node.children.forEach((child) => visit2(child, childrenVisible));
   }
 }
 function evaluateDisabled(schema, ctx) {
@@ -2481,6 +2602,7 @@ function executeInvokeComputer(name, values, options) {
   const ctx = {
     values,
     resources: options?.resources ?? {},
+    env: options?.env ?? options?.environment?.env,
     ...options?.row !== void 0 ? { row: options.row } : {},
     ...options?.item !== void 0 ? { item: options.item } : {}
   };
@@ -2829,6 +2951,7 @@ var StepRunner = class {
       (condition) => evaluateCondition(condition, values, conditionState, {
         environment: this.environment,
         resources: this.engine.getResources(),
+        env: this.engine.getEnv(),
         ...options?.row !== void 0 ? { row: options.row } : {},
         ...options?.item !== void 0 ? { item: options.item } : {}
       })
@@ -2913,6 +3036,7 @@ var StepRunner = class {
     return {
       values: this.engine.getValues(),
       resources: this.engine.getResources(),
+      env: this.engine.getEnv(),
       ...options?.row !== void 0 ? { row: options.row } : {},
       ...options?.item !== void 0 ? { item: options.item } : {}
     };
@@ -2921,6 +3045,7 @@ var StepRunner = class {
     return {
       values: this.engine.getValues(),
       resources: this.engine.getResources(),
+      env: this.engine.getEnv(),
       ...options?.row !== void 0 ? { row: options.row } : {},
       ...options?.item !== void 0 ? { item: options.item } : {}
     };
@@ -2930,6 +3055,7 @@ function resolveApiRequestBody(step, engine, options) {
   const ctx = {
     values: engine.getValues(),
     resources: engine.getResources(),
+    env: engine.getEnv(),
     ...options?.row !== void 0 ? { row: options.row } : {},
     ...options?.item !== void 0 ? { item: options.item } : {}
   };
@@ -2949,10 +3075,11 @@ function resolveApiRequestUrl(step, engine, options) {
   const ctx = {
     values: engine.getValues(),
     resources: engine.getResources(),
+    env: engine.getEnv(),
     ...options?.row !== void 0 ? { row: options.row } : {},
     ...options?.item !== void 0 ? { item: options.item } : {}
   };
-  const url = resolveApiUrlTemplate(step.request.url, ctx);
+  const url = resolveApiUrlTemplate(step.request.url, ctx, engine.getEnvDefinitions());
   const hasQueryFrom = "queryFrom" in step.request && step.request.queryFrom !== void 0;
   const hasQuery = "query" in step.request && step.request.query !== void 0;
   if (hasQueryFrom && hasQuery) {
@@ -3245,11 +3372,11 @@ function collectTemplate(node, fields, nested) {
 }
 function collectValuesRepeatFieldIds(metas) {
   const ids = /* @__PURE__ */ new Set();
-  const visit = (meta) => {
+  const visit2 = (meta) => {
     meta.fieldTemplates.forEach((node) => ids.add(node.id));
-    meta.nested.forEach(visit);
+    meta.nested.forEach(visit2);
   };
-  metas.forEach(visit);
+  metas.forEach(visit2);
   return ids;
 }
 function createDefaultRepeatItem(meta) {
@@ -3337,9 +3464,11 @@ function findValuesRepeatMeta(metas, repeatId) {
 
 // src/engine/form-engine.ts
 var FormEngine = class {
-  constructor(runtimeTree, environment = {}) {
+  constructor(runtimeTree, environment = {}, envConfig = {}) {
     this.runtimeTree = runtimeTree;
-    this.environment = createFormEngineEnvironment(environment);
+    this.envConfig = structuredClone(envConfig);
+    validateFormEnvReferences(this.runtimeTree.schema, this.envConfig.definitions);
+    this.environment = createFormEngineEnvironment({ ...environment, env: resolveFormEnv(this.envConfig, false) });
     this.stepRunner = new StepRunner(this, this.environment);
     this.buildNodeIndexes();
     this.buildDependencyGraph();
@@ -3365,6 +3494,13 @@ var FormEngine = class {
   graph = new DependencyGraph();
   stepRunner;
   environment;
+  envConfig;
+  getEnvDefinitions() {
+    return structuredClone(this.envConfig.definitions ?? {});
+  }
+  getEnv() {
+    return this.environment.env ?? Object.freeze({});
+  }
   fieldNodes = /* @__PURE__ */ new Map();
   actionNodes = /* @__PURE__ */ new Map();
   displayNodes = /* @__PURE__ */ new Map();
@@ -3434,6 +3570,7 @@ var FormEngine = class {
     this.notifyStateUpdated();
     return this.batch(async () => {
       try {
+        this.environment.env = resolveFormEnv(this.envConfig, !this.skipLoadStepsOnInitialize);
         this.hydrateValues(this.runtimeTree);
         if (!this.skipLoadStepsOnInitialize) {
           await this.runLoadSteps();
@@ -3881,7 +4018,8 @@ var FormEngine = class {
       getPath(
         {
           values: this.values,
-          resources: this.resources
+          resources: this.resources,
+          env: this.getEnv()
         },
         path
       )
@@ -3972,7 +4110,8 @@ var FormEngine = class {
     this.reevaluateConditions();
     const result = runSubmitPipeline(this.getSnapshot(), {
       environment: this.environment,
-      resources: this.resources
+      resources: this.resources,
+      env: this.getEnv()
     });
     const itemErrors = {};
     this.itemFieldState.forEach((state, name) => {
@@ -4363,7 +4502,8 @@ var FormEngine = class {
       value: changedField === "__bulk__" ? void 0 : nextValues[changedField],
       state: this.getConditionState(),
       environment: this.environment,
-      resources: this.resources
+      resources: this.resources,
+      env: this.getEnv()
     });
     this.validateValuesRepeatFields(
       changedFields.filter((name) => name.includes("."))
@@ -4389,7 +4529,8 @@ var FormEngine = class {
       value: void 0,
       state: this.getConditionState(),
       environment: this.environment,
-      resources: this.resources
+      resources: this.resources,
+      env: this.getEnv()
     };
   }
   getConditionState() {
@@ -4409,7 +4550,8 @@ var FormEngine = class {
       value: void 0,
       state: this.getConditionState(),
       environment: this.environment,
-      resources: this.resources
+      resources: this.resources,
+      env: this.getEnv()
     });
   }
   syncPendingState() {
@@ -4611,7 +4753,8 @@ var FormEngine = class {
         {
           environment: this.environment,
           values: this.values,
-          resources: this.resources
+          resources: this.resources,
+          env: this.getEnv()
         }
       );
       node.state.error = result.error;
@@ -4668,7 +4811,8 @@ var FormEngine = class {
     const source = resolveScopedPath(
       {
         values: this.values,
-        resources: this.resources
+        resources: this.resources,
+        env: this.getEnv()
       },
       options.source
     );
@@ -4695,6 +4839,7 @@ var FormEngine = class {
       {
         values: this.values,
         resources: this.resources,
+        env: this.getEnv(),
         ...options?.item !== void 0 ? { item: options.item } : {}
       },
       data.source
@@ -4720,6 +4865,7 @@ var FormEngine = class {
         executeComputed(schema.computed, this.values, {
           environment: this.environment,
           resources: this.resources,
+          env: this.getEnv(),
           ...options?.item !== void 0 ? { item: options.item } : {}
         })
       );
@@ -4731,6 +4877,7 @@ var FormEngine = class {
           {
             values: this.values,
             resources: this.resources,
+            env: this.getEnv(),
             ...options?.item !== void 0 ? { item: options.item } : {}
           },
           props.from
@@ -4754,6 +4901,7 @@ var FormEngine = class {
         {
           values: this.values,
           resources: this.resources,
+          env: this.getEnv(),
           ...options?.item !== void 0 ? { item: options.item } : {}
         },
         props.from
@@ -4785,6 +4933,7 @@ var FormEngine = class {
           {
             values: this.values,
             resources: this.resources,
+            env: this.getEnv(),
             ...options?.item !== void 0 ? { item: options.item } : {}
           },
           props.titleFrom
@@ -4824,7 +4973,8 @@ var FormEngine = class {
     const source = resolveScopedPath(
       {
         values: this.values,
-        resources: this.resources
+        resources: this.resources,
+        env: this.getEnv()
       },
       props.source
     );
@@ -5013,6 +5163,7 @@ var FormEngine = class {
       {
         values: this.values,
         resources: this.resources,
+        env: this.getEnv(),
         ...options.item !== void 0 ? { item: options.item } : {}
       },
       options.from.trim()
@@ -5031,7 +5182,7 @@ var FormEngine = class {
   }
   validateValuesRepeatFields(only) {
     const targets = only ? new Set(only) : void 0;
-    const visit = (meta, absolutePath) => {
+    const visit2 = (meta, absolutePath) => {
       const items = readRepeatArray(this.values, absolutePath);
       items.forEach((item, index) => {
         meta.fieldTemplates.forEach((template, fieldName) => {
@@ -5049,20 +5200,21 @@ var FormEngine = class {
           const result = validateField(template.schema, value, {
             environment: this.environment,
             values: this.values,
-            resources: this.resources
+            resources: this.resources,
+            env: this.getEnv()
           });
           const state = this.ensureItemFieldState(scopedName);
           state.error = result.error;
         });
         meta.nested.forEach((nested) => {
-          visit(nested, `${absolutePath}.${index}.${nested.path}`);
+          visit2(nested, `${absolutePath}.${index}.${nested.path}`);
         });
       });
     };
-    this.valuesRepeatMetas.forEach((meta) => visit(meta, meta.path));
+    this.valuesRepeatMetas.forEach((meta) => visit2(meta, meta.path));
   }
   touchAllValuesRepeatFields() {
-    const visit = (meta, absolutePath) => {
+    const visit2 = (meta, absolutePath) => {
       const items = readRepeatArray(this.values, absolutePath);
       items.forEach((_, index) => {
         meta.fieldTemplates.forEach((_2, fieldName) => {
@@ -5070,11 +5222,11 @@ var FormEngine = class {
           this.ensureItemFieldState(scopedName).touched = true;
         });
         meta.nested.forEach((nested) => {
-          visit(nested, `${absolutePath}.${index}.${nested.path}`);
+          visit2(nested, `${absolutePath}.${index}.${nested.path}`);
         });
       });
     };
-    this.valuesRepeatMetas.forEach((meta) => visit(meta, meta.path));
+    this.valuesRepeatMetas.forEach((meta) => visit2(meta, meta.path));
   }
   pruneItemFieldState(absolutePath, removedIndex, previousLength) {
     const next = /* @__PURE__ */ new Map();
@@ -5271,19 +5423,25 @@ function findNode(node, name) {
   adaptDisplay,
   adaptField,
   adaptLayout,
+  collectFormEnvReferences,
   compileSchema,
   conditions,
   createFormEngineEnvironment,
   createRuntimeNode,
   formatTagSourceValue,
   isThenable,
+  remapFormEnvReferences,
+  resolveFormEnv,
   resolveLoadingProp,
   resolveTagValueMapping,
   runConditionEngine,
   tagMapKey,
   traverseNode,
   validateApiUrlTemplate,
+  validateEnvBaseUrl,
+  validateEnvDefinitions,
   validateField,
+  validateFormEnvReferences,
   validateSchema,
   validation,
   validationRegistry

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import * as _bsm_form_schema from '@bsm-form/schema';
-import { ToastVariant, ToastPosition, Condition, DisplayEventType, FieldEventType, TableInteraction, DialogEventType, DrawerEventType, RepeatOperation, Node, ActionNode, DisplayNode, FieldNode, LayoutNode, ValidationRule, FormSchema, TableTagValueMapping } from '@bsm-form/schema';
+import { FormEnvValues, ToastVariant, ToastPosition, Condition, FormEnvConfig, DisplayEventType, FieldEventType, TableInteraction, DialogEventType, DrawerEventType, RepeatOperation, Node, ActionNode, DisplayNode, FieldNode, LayoutNode, ValidationRule, FormSchema, TableTagValueMapping, FormEnvDefinitions } from '@bsm-form/schema';
 
 type FormEngineNotification = {
     message: string;
@@ -9,6 +9,7 @@ type FormEngineNotification = {
     duration?: number;
 };
 type InvokeContext = {
+    env?: FormEnvValues;
     values: Record<string, unknown>;
     resources: Record<string, unknown>;
     row?: Record<string, unknown>;
@@ -25,6 +26,7 @@ type ValidatorHandler = (ctx: InvokeContext) => true | string;
 /** Sync computed value producer. Must not return a Promise. */
 type ComputerHandler = (ctx: InvokeContext) => unknown;
 type FormEngineEnvironment = {
+    env?: FormEnvValues;
     request: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
     log: (message: string) => void;
     navigate: (to: string) => void;
@@ -85,6 +87,9 @@ declare class FormEngine {
     private graph;
     private stepRunner;
     private environment;
+    private envConfig;
+    getEnvDefinitions(): _bsm_form_schema.FormEnvDefinitions;
+    getEnv(): FormEnvValues;
     private fieldNodes;
     private actionNodes;
     private displayNodes;
@@ -110,7 +115,7 @@ declare class FormEngine {
     private hasPendingStateUpdate;
     private initializationPromise?;
     private skipLoadStepsOnInitialize;
-    constructor(runtimeTree: RuntimeNode, environment?: Partial<FormEngineEnvironment>);
+    constructor(runtimeTree: RuntimeNode, environment?: Partial<FormEngineEnvironment>, envConfig?: FormEnvConfig);
     runLoadSteps(): Promise<void>;
     initialize(options?: {
         skipLoadSteps?: boolean;
@@ -335,6 +340,7 @@ type FormSnapshot = {
     nodes: Map<string, RuntimeNode>;
 };
 type PipelineContext = {
+    env?: Readonly<Record<string, string | number | boolean>>;
     tree: RuntimeNode;
     values: FormValues;
     changedField: string;
@@ -509,6 +515,7 @@ declare const validationRegistry: ValidationRegistry;
 
 type ValidateFieldOptions = {
     environment?: FormEngineEnvironment;
+    env?: Readonly<Record<string, string | number | boolean>>;
     values?: Record<string, unknown>;
     resources?: Record<string, unknown>;
     row?: Record<string, unknown>;
@@ -591,4 +598,16 @@ declare function formatTagSourceValue(value: unknown): string;
 /** Validates syntax without reading values or running author code. */
 declare function validateApiUrlTemplate(url: string): void;
 
-export { type AccordionChangeReason, type AccordionChangeResult, type AccordionState, type ActionAdapterInput, type ActionContext, type ActionHandler, type ComputerHandler, DependencyGraph, type DependencyMap, type DialogState, type DialogTransitionReason, type DialogTransitionResult, type DisplayAdapterInput, type DrawerState, type DrawerTransitionReason, type DrawerTransitionResult, EventBus, type FieldAdapterInput, FormEngine, type FormEngineConfig, type FormEngineEnvironment, type FormEngineNotification, type FormEngineState, type FormErrors, type FormEvent, type FormSnapshot, type FormState, type FormValues, type InitializationStatus, type InvokeContext, type InvokeHandler, type LayoutAdapterInput, type Listener, type OptionsConfig, type PaginationChangeReason, type PaginationChangeResult, type PaginationState, type PipelineContext, type PredicateHandler, type RepeatMutationReason, type RepeatMutationResult, type RuntimeNode, type RuntimeNodeState, type RuntimeTree, type StepRunOptions, type StepperNavigationReason, type StepperNavigationResult, type StepperState, type TabsChangeReason, type TabsChangeResult, type TabsState, type ValidateFieldOptions, type ValidationResult, type Validator, type ValidatorHandler, adaptAction, adaptDisplay, adaptField, adaptLayout, compileSchema, conditions, createFormEngineEnvironment, createRuntimeNode, formatTagSourceValue, isThenable, resolveLoadingProp, resolveTagValueMapping, runConditionEngine, tagMapKey, traverseNode, validateApiUrlTemplate, validateField, validateSchema, validation, validationRegistry };
+type FormEnvReference = {
+    name: string;
+    path: string;
+};
+declare function collectFormEnvReferences(schema: unknown): FormEnvReference[];
+declare function validateFormEnvReferences(schema: unknown, definitions?: FormEnvDefinitions): void;
+declare function remapFormEnvReferences<T>(schema: T, previous: string, next: string): T;
+
+declare function validateEnvBaseUrl(value: string): void;
+declare function validateEnvDefinitions(value: unknown): asserts value is FormEnvDefinitions;
+declare function resolveFormEnv(config?: FormEnvConfig, requireValues?: boolean): FormEnvValues;
+
+export { type AccordionChangeReason, type AccordionChangeResult, type AccordionState, type ActionAdapterInput, type ActionContext, type ActionHandler, type ComputerHandler, DependencyGraph, type DependencyMap, type DialogState, type DialogTransitionReason, type DialogTransitionResult, type DisplayAdapterInput, type DrawerState, type DrawerTransitionReason, type DrawerTransitionResult, EventBus, type FieldAdapterInput, FormEngine, type FormEngineConfig, type FormEngineEnvironment, type FormEngineNotification, type FormEngineState, type FormErrors, type FormEvent, type FormSnapshot, type FormState, type FormValues, type InitializationStatus, type InvokeContext, type InvokeHandler, type LayoutAdapterInput, type Listener, type OptionsConfig, type PaginationChangeReason, type PaginationChangeResult, type PaginationState, type PipelineContext, type PredicateHandler, type RepeatMutationReason, type RepeatMutationResult, type RuntimeNode, type RuntimeNodeState, type RuntimeTree, type StepRunOptions, type StepperNavigationReason, type StepperNavigationResult, type StepperState, type TabsChangeReason, type TabsChangeResult, type TabsState, type ValidateFieldOptions, type ValidationResult, type Validator, type ValidatorHandler, adaptAction, adaptDisplay, adaptField, adaptLayout, collectFormEnvReferences, compileSchema, conditions, createFormEngineEnvironment, createRuntimeNode, formatTagSourceValue, isThenable, remapFormEnvReferences, resolveFormEnv, resolveLoadingProp, resolveTagValueMapping, runConditionEngine, tagMapKey, traverseNode, validateApiUrlTemplate, validateEnvBaseUrl, validateEnvDefinitions, validateField, validateFormEnvReferences, validateSchema, validation, validationRegistry };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as _bsm_form_schema from '@bsm-form/schema';
-import { ToastVariant, ToastPosition, Condition, DisplayEventType, FieldEventType, TableInteraction, DialogEventType, DrawerEventType, RepeatOperation, Node, ActionNode, DisplayNode, FieldNode, LayoutNode, ValidationRule, FormSchema, TableTagValueMapping } from '@bsm-form/schema';
+import { FormEnvValues, ToastVariant, ToastPosition, Condition, FormEnvConfig, DisplayEventType, FieldEventType, TableInteraction, DialogEventType, DrawerEventType, RepeatOperation, Node, ActionNode, DisplayNode, FieldNode, LayoutNode, ValidationRule, FormSchema, TableTagValueMapping, FormEnvDefinitions } from '@bsm-form/schema';
 
 type FormEngineNotification = {
     message: string;
@@ -9,6 +9,7 @@ type FormEngineNotification = {
     duration?: number;
 };
 type InvokeContext = {
+    env?: FormEnvValues;
     values: Record<string, unknown>;
     resources: Record<string, unknown>;
     row?: Record<string, unknown>;
@@ -25,6 +26,7 @@ type ValidatorHandler = (ctx: InvokeContext) => true | string;
 /** Sync computed value producer. Must not return a Promise. */
 type ComputerHandler = (ctx: InvokeContext) => unknown;
 type FormEngineEnvironment = {
+    env?: FormEnvValues;
     request: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
     log: (message: string) => void;
     navigate: (to: string) => void;
@@ -85,6 +87,9 @@ declare class FormEngine {
     private graph;
     private stepRunner;
     private environment;
+    private envConfig;
+    getEnvDefinitions(): _bsm_form_schema.FormEnvDefinitions;
+    getEnv(): FormEnvValues;
     private fieldNodes;
     private actionNodes;
     private displayNodes;
@@ -110,7 +115,7 @@ declare class FormEngine {
     private hasPendingStateUpdate;
     private initializationPromise?;
     private skipLoadStepsOnInitialize;
-    constructor(runtimeTree: RuntimeNode, environment?: Partial<FormEngineEnvironment>);
+    constructor(runtimeTree: RuntimeNode, environment?: Partial<FormEngineEnvironment>, envConfig?: FormEnvConfig);
     runLoadSteps(): Promise<void>;
     initialize(options?: {
         skipLoadSteps?: boolean;
@@ -335,6 +340,7 @@ type FormSnapshot = {
     nodes: Map<string, RuntimeNode>;
 };
 type PipelineContext = {
+    env?: Readonly<Record<string, string | number | boolean>>;
     tree: RuntimeNode;
     values: FormValues;
     changedField: string;
@@ -509,6 +515,7 @@ declare const validationRegistry: ValidationRegistry;
 
 type ValidateFieldOptions = {
     environment?: FormEngineEnvironment;
+    env?: Readonly<Record<string, string | number | boolean>>;
     values?: Record<string, unknown>;
     resources?: Record<string, unknown>;
     row?: Record<string, unknown>;
@@ -591,4 +598,16 @@ declare function formatTagSourceValue(value: unknown): string;
 /** Validates syntax without reading values or running author code. */
 declare function validateApiUrlTemplate(url: string): void;
 
-export { type AccordionChangeReason, type AccordionChangeResult, type AccordionState, type ActionAdapterInput, type ActionContext, type ActionHandler, type ComputerHandler, DependencyGraph, type DependencyMap, type DialogState, type DialogTransitionReason, type DialogTransitionResult, type DisplayAdapterInput, type DrawerState, type DrawerTransitionReason, type DrawerTransitionResult, EventBus, type FieldAdapterInput, FormEngine, type FormEngineConfig, type FormEngineEnvironment, type FormEngineNotification, type FormEngineState, type FormErrors, type FormEvent, type FormSnapshot, type FormState, type FormValues, type InitializationStatus, type InvokeContext, type InvokeHandler, type LayoutAdapterInput, type Listener, type OptionsConfig, type PaginationChangeReason, type PaginationChangeResult, type PaginationState, type PipelineContext, type PredicateHandler, type RepeatMutationReason, type RepeatMutationResult, type RuntimeNode, type RuntimeNodeState, type RuntimeTree, type StepRunOptions, type StepperNavigationReason, type StepperNavigationResult, type StepperState, type TabsChangeReason, type TabsChangeResult, type TabsState, type ValidateFieldOptions, type ValidationResult, type Validator, type ValidatorHandler, adaptAction, adaptDisplay, adaptField, adaptLayout, compileSchema, conditions, createFormEngineEnvironment, createRuntimeNode, formatTagSourceValue, isThenable, resolveLoadingProp, resolveTagValueMapping, runConditionEngine, tagMapKey, traverseNode, validateApiUrlTemplate, validateField, validateSchema, validation, validationRegistry };
+type FormEnvReference = {
+    name: string;
+    path: string;
+};
+declare function collectFormEnvReferences(schema: unknown): FormEnvReference[];
+declare function validateFormEnvReferences(schema: unknown, definitions?: FormEnvDefinitions): void;
+declare function remapFormEnvReferences<T>(schema: T, previous: string, next: string): T;
+
+declare function validateEnvBaseUrl(value: string): void;
+declare function validateEnvDefinitions(value: unknown): asserts value is FormEnvDefinitions;
+declare function resolveFormEnv(config?: FormEnvConfig, requireValues?: boolean): FormEnvValues;
+
+export { type AccordionChangeReason, type AccordionChangeResult, type AccordionState, type ActionAdapterInput, type ActionContext, type ActionHandler, type ComputerHandler, DependencyGraph, type DependencyMap, type DialogState, type DialogTransitionReason, type DialogTransitionResult, type DisplayAdapterInput, type DrawerState, type DrawerTransitionReason, type DrawerTransitionResult, EventBus, type FieldAdapterInput, FormEngine, type FormEngineConfig, type FormEngineEnvironment, type FormEngineNotification, type FormEngineState, type FormErrors, type FormEvent, type FormSnapshot, type FormState, type FormValues, type InitializationStatus, type InvokeContext, type InvokeHandler, type LayoutAdapterInput, type Listener, type OptionsConfig, type PaginationChangeReason, type PaginationChangeResult, type PaginationState, type PipelineContext, type PredicateHandler, type RepeatMutationReason, type RepeatMutationResult, type RuntimeNode, type RuntimeNodeState, type RuntimeTree, type StepRunOptions, type StepperNavigationReason, type StepperNavigationResult, type StepperState, type TabsChangeReason, type TabsChangeResult, type TabsState, type ValidateFieldOptions, type ValidationResult, type Validator, type ValidatorHandler, adaptAction, adaptDisplay, adaptField, adaptLayout, collectFormEnvReferences, compileSchema, conditions, createFormEngineEnvironment, createRuntimeNode, formatTagSourceValue, isThenable, remapFormEnvReferences, resolveFormEnv, resolveLoadingProp, resolveTagValueMapping, runConditionEngine, tagMapKey, traverseNode, validateApiUrlTemplate, validateEnvBaseUrl, validateEnvDefinitions, validateField, validateFormEnvReferences, validateSchema, validation, validationRegistry };

package/dist/index.js

@@ -1,3 +1,58 @@
+// src/utils/form-env.ts
+function validateEnvBaseUrl(value) {
+  if (!value || /[\\\s?#]/.test(value) || value.startsWith("//")) throw new Error("Base URL cannot contain whitespace, query, fragment, or backslashes");
+  if (value.startsWith("/")) return;
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error("Expected an http(s) URL or path starting with /");
+  }
+  if (!["http:", "https:"].includes(url.protocol) || url.username || url.password) throw new Error("Base URL must use http(s) without credentials");
+}
+function validateValue(name, type, value) {
+  if (typeof value !== (type === "url" ? "string" : type) || typeof value === "number" && !Number.isFinite(value)) throw new Error(`env.${name}: expected ${String(type)}`);
+  if (type === "url") {
+    try {
+      validateEnvBaseUrl(value);
+    } catch (error) {
+      throw new Error(`env.${name}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+}
+function validateEnvDefinitions(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("Environment definitions must be an object");
+  for (const [name, entry] of Object.entries(value)) {
+    if (!/^[A-Za-z_]+$/.test(name) || ["__proto__", "prototype", "constructor"].includes(name)) throw new Error(`Invalid environment variable name: ${name}`);
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) throw new Error(`env.${name}: expected a definition`);
+    const definition = entry;
+    if (!["string", "number", "boolean", "url"].includes(String(definition.type))) throw new Error(`env.${name}: invalid type`);
+    for (const key of Object.keys(definition)) if (!["type", "label", "description", "default", "required", "allowOverride"].includes(key)) throw new Error(`env.${name}: unknown property ${key}`);
+    for (const key of ["required", "allowOverride"]) if (definition[key] !== void 0 && typeof definition[key] !== "boolean") throw new Error(`env.${name}.${key}: expected boolean`);
+    for (const key of ["label", "description"]) if (definition[key] !== void 0 && typeof definition[key] !== "string") throw new Error(`env.${name}.${key}: expected string`);
+    if (Object.hasOwn(definition, "default")) validateValue(name, definition.type, definition.default);
+  }
+}
+function resolveFormEnv(config = {}, requireValues = true) {
+  const definitions = config.definitions ?? {};
+  const overrides = config.overrides ?? {};
+  validateEnvDefinitions(definitions);
+  if (typeof overrides !== "object" || Array.isArray(overrides)) throw new Error("Environment overrides must be an object");
+  for (const name of Object.keys(overrides)) {
+    if (!Object.hasOwn(definitions, name)) throw new Error(`env.${name}: unknown override`);
+    if (definitions[name]?.allowOverride === false) throw new Error(`env.${name}: overrides are disabled`);
+  }
+  const values = {};
+  for (const [name, definition] of Object.entries(definitions)) {
+    const provided = Object.hasOwn(overrides, name);
+    const value = provided ? overrides[name] : definition.default;
+    if (provided || value !== void 0) validateValue(name, definition.type, value);
+    if (requireValues && definition.required && (value === void 0 || value === "")) throw new Error(`env.${name}: required value is missing`);
+    if (value !== void 0) values[name] = value;
+  }
+  return Object.freeze(values);
+}
+
 // src/utils/get-path.ts
 function pathSegments(path) {
   const segments = [];
@@ -45,6 +100,8 @@ function getPath(obj, path) {
 
 // src/utils/scope-path.ts
 function resolveScopedPath(ctx, path) {
+  if (path === "env") return ctx.env ?? {};
+  if (path.startsWith("env.")) return getPath(ctx.env ?? {}, path.slice(4));
   if (path === "$values" || path === "values") {
     return ctx.values;
   }
@@ -72,7 +129,7 @@ function resolveScopedPath(ctx, path) {
   return getPath(ctx.values, path);
 }
 function isExplicitScopedPath(path) {
-  return path === "$values" || path === "values" || path === "$resources" || path === "resources" || path === "$row" || path === "row" || path === "$item" || path === "item" || path.startsWith("values.") || path.startsWith("resources.") || path.startsWith("row.") || path.startsWith("item.");
+  return path === "env" || path.startsWith("env.") || path === "$values" || path === "values" || path === "$resources" || path === "resources" || path === "$row" || path === "row" || path === "$item" || path === "item" || path.startsWith("values.") || path.startsWith("resources.") || path.startsWith("row.") || path.startsWith("item.");
 }
 function resolvePathStringsInData(value, ctx) {
   if (typeof value === "string") {
@@ -92,7 +149,7 @@ function resolvePathStringsInData(value, ctx) {
 }
 
 // src/utils/url-template.ts
-var pathPattern = /^(values|resources)\.[A-Za-z_$][\w$]*(?:(?:\.(?:[A-Za-z_$][\w$]*|\d+))|(?:\[\d+\]))*$/;
+var pathPattern = /^(values|resources|env)\.[A-Za-z_$][\w$]*(?:(?:\.(?:[A-Za-z_$][\w$]*|\d+))|(?:\[\d+\]))*$/;
 function placeholders(url) {
   const result = [];
   let cursor = 0;
@@ -103,10 +160,10 @@ function placeholders(url) {
     if (close < 0) throw new Error("API URL template has an unclosed placeholder");
     const path = url.slice(start + 2, close).trim();
     if (!pathPattern.test(path)) {
-      throw new Error(`Invalid API URL placeholder: ${path}. Use a values.* or resources.* data path`);
+      throw new Error(`Invalid API URL placeholder: ${path}. Use a values.*, resources.*, or env.* data path`);
     }
     const origin = url.match(/^(?:[A-Za-z][A-Za-z0-9+.-]*:)?\/\/[^/?#]*/)?.[0];
-    if (start === 0 || origin && start < origin.length) {
+    if (start === 0 && !path.startsWith("env.") || origin && start < origin.length) {
       throw new Error("API URL placeholders cannot replace the service origin; use a static base URL");
     }
     result.push({ start, end: close + 1, path });
@@ -118,7 +175,7 @@ function validateApiUrlTemplate(url) {
   if (!url.trim()) throw new Error("API URL must not be empty");
   placeholders(url);
 }
-function resolveApiUrlTemplate(url, context) {
+function resolveApiUrlTemplate(url, context, definitions = {}) {
   validateApiUrlTemplate(url);
   let result = "";
   let cursor = 0;
@@ -130,7 +187,17 @@ function resolveApiUrlTemplate(url, context) {
     if (value === "." || value === "..") {
       throw new Error(`API URL placeholder ${placeholder.path} cannot be a dot segment`);
     }
-    result += url.slice(cursor, placeholder.start) + encodeURIComponent(String(value));
+    if (placeholder.start === 0 && placeholder.path.startsWith("env.")) {
+      if (definitions[placeholder.path.slice(4)]?.type !== "url" || typeof value !== "string") {
+        throw new Error(`${placeholder.path}: only an env variable of type url can supply a base URL`);
+      }
+      validateEnvBaseUrl(value);
+      const suffix = url.slice(placeholder.end);
+      if (suffix && !suffix.startsWith("/")) throw new Error("Base URL placeholder must be followed by / or end of URL");
+      result += suffix.startsWith("/") ? value.replace(/\/+$/, "") : value;
+    } else {
+      result += url.slice(cursor, placeholder.start) + encodeURIComponent(String(value));
+    }
     cursor = placeholder.end;
   }
   return result + url.slice(cursor);
@@ -1562,6 +1629,7 @@ function validateDrawerStepReferences(context) {
 }
 function validateStepConditionReferences(context) {
   context.stepConditionReferences.forEach(({ path, field }) => {
+    if (field.startsWith("env.")) return;
     if (isReservedConditionField(field)) {
       if (isPendingActionConditionField(field)) {
         const actionId = pendingActionIdFromField(field);
@@ -1722,6 +1790,7 @@ var validationRegistry = {
 // src/engine/environment.ts
 function createFormEngineEnvironment(overrides = {}) {
   return {
+    env: overrides.env ?? Object.freeze({}),
     request: overrides.request ?? defaultRequest,
     log: overrides.log ?? defaultLog,
     navigate: overrides.navigate ?? defaultNavigate,
@@ -1791,6 +1860,7 @@ function runInvokeValidator(rule, options) {
   const ctx = {
     values: options?.values ?? {},
     resources: options?.resources ?? {},
+    env: options?.env ?? options?.environment?.env,
     ...options?.row !== void 0 ? { row: options.row } : {},
     ...options?.item !== void 0 ? { item: options.item } : {}
   };
@@ -1895,6 +1965,7 @@ function evaluateCondition(condition, values, state, options) {
   }
   const target = resolveConditionTarget(condition.field, values, state, {
     resources: options?.resources,
+    env: options?.env ?? options?.environment?.env,
     ...options?.row !== void 0 ? { row: options.row } : {},
     ...options?.item !== void 0 ? { item: options.item } : {}
   });
@@ -1941,6 +2012,7 @@ function evaluateInvokeCondition(name, values, options) {
   const ctx = {
     values,
     resources: options?.resources ?? {},
+    env: options?.env ?? options?.environment?.env,
     ...options?.row !== void 0 ? { row: options.row } : {},
     ...options?.item !== void 0 ? { item: options.item } : {}
   };
@@ -1995,6 +2067,7 @@ function resolveConditionTarget(field, values, state, options) {
     {
       values,
       resources: options?.resources ?? {},
+      env: options?.env,
       ...options?.row !== void 0 ? { row: options.row } : {},
       ...options?.item !== void 0 ? { item: options.item } : {}
     },
@@ -2294,7 +2367,7 @@ var DependencyGraph = class {
     return ordered;
   }
   extractDependencies(conditions2) {
-    return conditions2.filter(isFieldCondition2).map((condition) => condition.field).filter((field) => !isReservedConditionField3(field));
+    return conditions2.filter(isFieldCondition2).map((condition) => condition.field).filter((field) => !isReservedConditionField3(field) && !field.startsWith("env."));
   }
   clear() {
     this.forward.clear();
@@ -2316,10 +2389,52 @@ var EventBus = class {
   }
 };
 
+// src/utils/env-references.ts
+var pathKeys = /* @__PURE__ */ new Set(["from", "source", "field", "path", "bodyFrom", "queryFrom"]);
+function visit(value, path, key, data, transform) {
+  if (typeof value === "string") {
+    if (key === "url") return transform(value, path, true);
+    if ((pathKeys.has(key) || path.endsWith(".bind.value") || data) && /^env\.[A-Za-z_]/.test(value)) return transform(value, path, false);
+    return value;
+  }
+  if (Array.isArray(value)) return value.map((item, index) => visit(item, `${path}[${index}]`, key, data, transform));
+  if (value && typeof value === "object") return Object.fromEntries(Object.entries(value).map(([childKey, child]) => [
+    childKey,
+    visit(child, `${path}.${childKey}`, childKey, data || childKey === "body" || childKey === "query", transform)
+  ]));
+  return value;
+}
+function collectFormEnvReferences(schema) {
+  const references = [];
+  visit(schema, "schema", "", false, (value, path, template) => {
+    if (template) {
+      for (const match of value.matchAll(/\$\{\s*env\.([A-Za-z_][A-Za-z0-9_]*)\s*\}/g)) {
+        references.push({ name: match[1], path });
+      }
+    } else references.push({ name: value.slice(4).split(/[.[]/)[0], path });
+    return value;
+  });
+  return references;
+}
+function validateFormEnvReferences(schema, definitions = {}) {
+  for (const reference of collectFormEnvReferences(schema)) {
+    if (!Object.hasOwn(definitions, reference.name)) throw new Error(`${reference.path}: undefined environment variable env.${reference.name}`);
+  }
+}
+function remapFormEnvReferences(schema, previous, next) {
+  return visit(schema, "schema", "", false, (value, _path, template) => {
+    if (template) return value.replace(
+      /\$\{\s*env\.([A-Za-z_][A-Za-z0-9_]*)\s*\}/g,
+      (original, name) => name === previous ? "${env." + next + "}" : original
+    );
+    return value === `env.${previous}` ? `env.${next}` : value;
+  });
+}
+
 // src/pipeline/run-conditions.ts
 function runConditions(ctx) {
-  visit(ctx.tree, true);
-  function visit(node, parentVisible) {
+  visit2(ctx.tree, true);
+  function visit2(node, parentVisible) {
     const schema = node.schema;
     const hasVisibilityConditions = schema.kind === "field" || schema.kind === "display" || schema.kind === "action" || schema.kind === "layout" && schema.type === "step";
     if (!parentVisible) {
@@ -2337,7 +2452,7 @@ function runConditions(ctx) {
     }
     node.state.disabled = evaluateDisabled(schema, ctx);
     const childrenVisible = node.state.visible && !(schema.kind === "layout" && (schema.type === "dialog" || schema.type === "drawer") && node.state.open !== true);
-    node.children.forEach((child) => visit(child, childrenVisible));
+    node.children.forEach((child) => visit2(child, childrenVisible));
   }
 }
 function evaluateDisabled(schema, ctx) {
@@ -2456,6 +2571,7 @@ function executeInvokeComputer(name, values, options) {
   const ctx = {
     values,
     resources: options?.resources ?? {},
+    env: options?.env ?? options?.environment?.env,
     ...options?.row !== void 0 ? { row: options.row } : {},
     ...options?.item !== void 0 ? { item: options.item } : {}
   };
@@ -2804,6 +2920,7 @@ var StepRunner = class {
       (condition) => evaluateCondition(condition, values, conditionState, {
         environment: this.environment,
         resources: this.engine.getResources(),
+        env: this.engine.getEnv(),
         ...options?.row !== void 0 ? { row: options.row } : {},
         ...options?.item !== void 0 ? { item: options.item } : {}
       })
@@ -2888,6 +3005,7 @@ var StepRunner = class {
     return {
       values: this.engine.getValues(),
       resources: this.engine.getResources(),
+      env: this.engine.getEnv(),
       ...options?.row !== void 0 ? { row: options.row } : {},
       ...options?.item !== void 0 ? { item: options.item } : {}
     };
@@ -2896,6 +3014,7 @@ var StepRunner = class {
     return {
       values: this.engine.getValues(),
       resources: this.engine.getResources(),
+      env: this.engine.getEnv(),
       ...options?.row !== void 0 ? { row: options.row } : {},
       ...options?.item !== void 0 ? { item: options.item } : {}
     };
@@ -2905,6 +3024,7 @@ function resolveApiRequestBody(step, engine, options) {
   const ctx = {
     values: engine.getValues(),
     resources: engine.getResources(),
+    env: engine.getEnv(),
     ...options?.row !== void 0 ? { row: options.row } : {},
     ...options?.item !== void 0 ? { item: options.item } : {}
   };
@@ -2924,10 +3044,11 @@ function resolveApiRequestUrl(step, engine, options) {
   const ctx = {
     values: engine.getValues(),
     resources: engine.getResources(),
+    env: engine.getEnv(),
     ...options?.row !== void 0 ? { row: options.row } : {},
     ...options?.item !== void 0 ? { item: options.item } : {}
   };
-  const url = resolveApiUrlTemplate(step.request.url, ctx);
+  const url = resolveApiUrlTemplate(step.request.url, ctx, engine.getEnvDefinitions());
   const hasQueryFrom = "queryFrom" in step.request && step.request.queryFrom !== void 0;
   const hasQuery = "query" in step.request && step.request.query !== void 0;
   if (hasQueryFrom && hasQuery) {
@@ -3220,11 +3341,11 @@ function collectTemplate(node, fields, nested) {
 }
 function collectValuesRepeatFieldIds(metas) {
   const ids = /* @__PURE__ */ new Set();
-  const visit = (meta) => {
+  const visit2 = (meta) => {
     meta.fieldTemplates.forEach((node) => ids.add(node.id));
-    meta.nested.forEach(visit);
+    meta.nested.forEach(visit2);
   };
-  metas.forEach(visit);
+  metas.forEach(visit2);
   return ids;
 }
 function createDefaultRepeatItem(meta) {
@@ -3312,9 +3433,11 @@ function findValuesRepeatMeta(metas, repeatId) {
 
 // src/engine/form-engine.ts
 var FormEngine = class {
-  constructor(runtimeTree, environment = {}) {
+  constructor(runtimeTree, environment = {}, envConfig = {}) {
     this.runtimeTree = runtimeTree;
-    this.environment = createFormEngineEnvironment(environment);
+    this.envConfig = structuredClone(envConfig);
+    validateFormEnvReferences(this.runtimeTree.schema, this.envConfig.definitions);
+    this.environment = createFormEngineEnvironment({ ...environment, env: resolveFormEnv(this.envConfig, false) });
     this.stepRunner = new StepRunner(this, this.environment);
     this.buildNodeIndexes();
     this.buildDependencyGraph();
@@ -3340,6 +3463,13 @@ var FormEngine = class {
   graph = new DependencyGraph();
   stepRunner;
   environment;
+  envConfig;
+  getEnvDefinitions() {
+    return structuredClone(this.envConfig.definitions ?? {});
+  }
+  getEnv() {
+    return this.environment.env ?? Object.freeze({});
+  }
   fieldNodes = /* @__PURE__ */ new Map();
   actionNodes = /* @__PURE__ */ new Map();
   displayNodes = /* @__PURE__ */ new Map();
@@ -3409,6 +3539,7 @@ var FormEngine = class {
     this.notifyStateUpdated();
     return this.batch(async () => {
       try {
+        this.environment.env = resolveFormEnv(this.envConfig, !this.skipLoadStepsOnInitialize);
         this.hydrateValues(this.runtimeTree);
         if (!this.skipLoadStepsOnInitialize) {
           await this.runLoadSteps();
@@ -3856,7 +3987,8 @@ var FormEngine = class {
       getPath(
         {
           values: this.values,
-          resources: this.resources
+          resources: this.resources,
+          env: this.getEnv()
         },
         path
       )
@@ -3947,7 +4079,8 @@ var FormEngine = class {
     this.reevaluateConditions();
     const result = runSubmitPipeline(this.getSnapshot(), {
       environment: this.environment,
-      resources: this.resources
+      resources: this.resources,
+      env: this.getEnv()
     });
     const itemErrors = {};
     this.itemFieldState.forEach((state, name) => {
@@ -4338,7 +4471,8 @@ var FormEngine = class {
       value: changedField === "__bulk__" ? void 0 : nextValues[changedField],
       state: this.getConditionState(),
       environment: this.environment,
-      resources: this.resources
+      resources: this.resources,
+      env: this.getEnv()
     });
     this.validateValuesRepeatFields(
       changedFields.filter((name) => name.includes("."))
@@ -4364,7 +4498,8 @@ var FormEngine = class {
       value: void 0,
       state: this.getConditionState(),
       environment: this.environment,
-      resources: this.resources
+      resources: this.resources,
+      env: this.getEnv()
     };
   }
   getConditionState() {
@@ -4384,7 +4519,8 @@ var FormEngine = class {
       value: void 0,
       state: this.getConditionState(),
       environment: this.environment,
-      resources: this.resources
+      resources: this.resources,
+      env: this.getEnv()
     });
   }
   syncPendingState() {
@@ -4586,7 +4722,8 @@ var FormEngine = class {
         {
           environment: this.environment,
           values: this.values,
-          resources: this.resources
+          resources: this.resources,
+          env: this.getEnv()
         }
       );
       node.state.error = result.error;
@@ -4643,7 +4780,8 @@ var FormEngine = class {
     const source = resolveScopedPath(
       {
         values: this.values,
-        resources: this.resources
+        resources: this.resources,
+        env: this.getEnv()
       },
       options.source
     );
@@ -4670,6 +4808,7 @@ var FormEngine = class {
       {
         values: this.values,
         resources: this.resources,
+        env: this.getEnv(),
         ...options?.item !== void 0 ? { item: options.item } : {}
       },
       data.source
@@ -4695,6 +4834,7 @@ var FormEngine = class {
         executeComputed(schema.computed, this.values, {
           environment: this.environment,
           resources: this.resources,
+          env: this.getEnv(),
           ...options?.item !== void 0 ? { item: options.item } : {}
         })
       );
@@ -4706,6 +4846,7 @@ var FormEngine = class {
           {
             values: this.values,
             resources: this.resources,
+            env: this.getEnv(),
             ...options?.item !== void 0 ? { item: options.item } : {}
           },
           props.from
@@ -4729,6 +4870,7 @@ var FormEngine = class {
         {
           values: this.values,
           resources: this.resources,
+          env: this.getEnv(),
           ...options?.item !== void 0 ? { item: options.item } : {}
         },
         props.from
@@ -4760,6 +4902,7 @@ var FormEngine = class {
           {
             values: this.values,
             resources: this.resources,
+            env: this.getEnv(),
             ...options?.item !== void 0 ? { item: options.item } : {}
           },
           props.titleFrom
@@ -4799,7 +4942,8 @@ var FormEngine = class {
     const source = resolveScopedPath(
       {
         values: this.values,
-        resources: this.resources
+        resources: this.resources,
+        env: this.getEnv()
       },
       props.source
     );
@@ -4988,6 +5132,7 @@ var FormEngine = class {
       {
         values: this.values,
         resources: this.resources,
+        env: this.getEnv(),
         ...options.item !== void 0 ? { item: options.item } : {}
       },
       options.from.trim()
@@ -5006,7 +5151,7 @@ var FormEngine = class {
   }
   validateValuesRepeatFields(only) {
     const targets = only ? new Set(only) : void 0;
-    const visit = (meta, absolutePath) => {
+    const visit2 = (meta, absolutePath) => {
       const items = readRepeatArray(this.values, absolutePath);
       items.forEach((item, index) => {
         meta.fieldTemplates.forEach((template, fieldName) => {
@@ -5024,20 +5169,21 @@ var FormEngine = class {
           const result = validateField(template.schema, value, {
             environment: this.environment,
             values: this.values,
-            resources: this.resources
+            resources: this.resources,
+            env: this.getEnv()
           });
           const state = this.ensureItemFieldState(scopedName);
           state.error = result.error;
         });
         meta.nested.forEach((nested) => {
-          visit(nested, `${absolutePath}.${index}.${nested.path}`);
+          visit2(nested, `${absolutePath}.${index}.${nested.path}`);
         });
       });
     };
-    this.valuesRepeatMetas.forEach((meta) => visit(meta, meta.path));
+    this.valuesRepeatMetas.forEach((meta) => visit2(meta, meta.path));
   }
   touchAllValuesRepeatFields() {
-    const visit = (meta, absolutePath) => {
+    const visit2 = (meta, absolutePath) => {
       const items = readRepeatArray(this.values, absolutePath);
       items.forEach((_, index) => {
         meta.fieldTemplates.forEach((_2, fieldName) => {
@@ -5045,11 +5191,11 @@ var FormEngine = class {
           this.ensureItemFieldState(scopedName).touched = true;
         });
         meta.nested.forEach((nested) => {
-          visit(nested, `${absolutePath}.${index}.${nested.path}`);
+          visit2(nested, `${absolutePath}.${index}.${nested.path}`);
         });
       });
     };
-    this.valuesRepeatMetas.forEach((meta) => visit(meta, meta.path));
+    this.valuesRepeatMetas.forEach((meta) => visit2(meta, meta.path));
   }
   pruneItemFieldState(absolutePath, removedIndex, previousLength) {
     const next = /* @__PURE__ */ new Map();
@@ -5245,19 +5391,25 @@ export {
   adaptDisplay,
   adaptField,
   adaptLayout,
+  collectFormEnvReferences,
   compileSchema,
   conditions,
   createFormEngineEnvironment,
   createRuntimeNode,
   formatTagSourceValue,
   isThenable,
+  remapFormEnvReferences,
+  resolveFormEnv,
   resolveLoadingProp,
   resolveTagValueMapping,
   runConditionEngine,
   tagMapKey,
   traverseNode,
   validateApiUrlTemplate,
+  validateEnvBaseUrl,
+  validateEnvDefinitions,
   validateField,
+  validateFormEnvReferences,
   validateSchema,
   validation,
   validationRegistry

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bsm-form/core",
-  "version": "0.40.0",
+  "version": "0.41.0",
   "description": "Framework-independent form engine for BSM FormSchema",
   "type": "module",
   "license": "UNLICENSED",
@@ -19,7 +19,7 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@bsm-form/schema": "0.40.0"
+    "@bsm-form/schema": "0.41.0"
   },
   "devDependencies": {
     "vitest": "^4.1.10"