@bsm-form/core 0.39.0 → 0.41.0

package/dist/index.cjs

@@ -27,24 +27,236 @@ __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 = [];
+  let i = 0;
+  while (i < path.length) {
+    const char = path[i];
+    if (char === ".") {
+      i += 1;
+      continue;
+    }
+    if (char === "[") {
+      const close = path.indexOf("]", i);
+      if (close === -1) {
+        segments.push(path.slice(i));
+        break;
+      }
+      segments.push(path.slice(i + 1, close));
+      i = close + 1;
+      continue;
+    }
+    let end = i;
+    while (end < path.length && path[end] !== "." && path[end] !== "[") {
+      end += 1;
+    }
+    if (end > i) {
+      segments.push(path.slice(i, end));
+    }
+    i = end;
+  }
+  return segments;
+}
+function getPath(obj, path) {
+  if (!path) {
+    return obj;
+  }
+  let current = obj;
+  for (const key of pathSegments(path)) {
+    if (typeof current !== "object" || current === null) {
+      return void 0;
+    }
+    current = current[key];
+  }
+  return current;
+}
+
+// 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;
+  }
+  if (path === "$resources" || path === "resources") {
+    return ctx.resources;
+  }
+  if (path === "$row" || path === "row") {
+    return ctx.row;
+  }
+  if (path === "$item" || path === "item") {
+    return ctx.item;
+  }
+  if (path.startsWith("values.")) {
+    return getPath(ctx.values, path.replace("values.", ""));
+  }
+  if (path.startsWith("resources.")) {
+    return getPath(ctx.resources, path.replace("resources.", ""));
+  }
+  if (path.startsWith("row.")) {
+    return ctx.row === void 0 ? void 0 : getPath(ctx.row, path.replace("row.", ""));
+  }
+  if (path.startsWith("item.")) {
+    return ctx.item === void 0 ? void 0 : getPath(ctx.item, path.replace("item.", ""));
+  }
+  return getPath(ctx.values, path);
+}
+function isExplicitScopedPath(path) {
+  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") {
+    return isExplicitScopedPath(value) ? resolveScopedPath(ctx, value) : value;
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => resolvePathStringsInData(item, ctx));
+  }
+  if (typeof value === "object" && value !== null) {
+    const result = {};
+    for (const [key, entry] of Object.entries(value)) {
+      result[key] = resolvePathStringsInData(entry, ctx);
+    }
+    return result;
+  }
+  return value;
+}
+
+// src/utils/url-template.ts
+var pathPattern = /^(values|resources|env)\.[A-Za-z_$][\w$]*(?:(?:\.(?:[A-Za-z_$][\w$]*|\d+))|(?:\[\d+\]))*$/;
+function placeholders(url) {
+  const result = [];
+  let cursor = 0;
+  while (true) {
+    const start = url.indexOf("${", cursor);
+    if (start < 0) break;
+    const close = url.indexOf("}", start + 2);
+    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.*, resources.*, or env.* data path`);
+    }
+    const origin = url.match(/^(?:[A-Za-z][A-Za-z0-9+.-]*:)?\/\/[^/?#]*/)?.[0];
+    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 });
+    cursor = close + 1;
+  }
+  return result;
+}
+function validateApiUrlTemplate(url) {
+  if (!url.trim()) throw new Error("API URL must not be empty");
+  placeholders(url);
+}
+function resolveApiUrlTemplate(url, context, definitions = {}) {
+  validateApiUrlTemplate(url);
+  let result = "";
+  let cursor = 0;
+  for (const placeholder of placeholders(url)) {
+    const value = resolveScopedPath(context, placeholder.path);
+    if (typeof value !== "string" && typeof value !== "number" && typeof value !== "boolean" || typeof value === "number" && !Number.isFinite(value) || value === "") {
+      throw new Error(`API URL placeholder ${placeholder.path} must resolve to a non-empty string, finite number, or boolean`);
+    }
+    if (value === "." || value === "..") {
+      throw new Error(`API URL placeholder ${placeholder.path} cannot be a dot segment`);
+    }
+    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);
+}
+
 // src/compiler/compile-schema.ts
 var import_schema = require("@bsm-form/schema");
 
@@ -1347,7 +1559,25 @@ function collectDrawerSteps(steps, path, context, owningDrawerId) {
     });
   });
 }
+function validateApiUrlsInSteps(steps, path) {
+  steps.forEach((step, index) => {
+    const stepPath = `${path}[${index}]`;
+    if (step.type === "when") {
+      validateApiUrlsInSteps(step.then, `${stepPath}.then`);
+      if (step.else) validateApiUrlsInSteps(step.else, `${stepPath}.else`);
+    }
+    if (step.type === "api") {
+      try {
+        validateApiUrlTemplate(step.request.url);
+      } catch (error) {
+        throw new Error(`Invalid API URL at ${stepPath}.request.url: ${error instanceof Error ? error.message : String(error)}`);
+      }
+      if (step.onError) validateApiUrlsInSteps(step.onError, `${stepPath}.onError`);
+    }
+  });
+}
 function collectDialogSteps(steps, path, context, owningDialogId) {
+  validateApiUrlsInSteps(steps, path);
   steps.forEach((step, index) => {
     if (step.type !== "dialog") {
       return;
@@ -1445,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);
@@ -1605,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,
@@ -1674,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 } : {}
   };
@@ -1759,99 +1992,6 @@ function isResourcePathInFlight(sourceRelative, inFlight) {
   );
 }
 
-// src/utils/get-path.ts
-function pathSegments(path) {
-  const segments = [];
-  let i = 0;
-  while (i < path.length) {
-    const char = path[i];
-    if (char === ".") {
-      i += 1;
-      continue;
-    }
-    if (char === "[") {
-      const close = path.indexOf("]", i);
-      if (close === -1) {
-        segments.push(path.slice(i));
-        break;
-      }
-      segments.push(path.slice(i + 1, close));
-      i = close + 1;
-      continue;
-    }
-    let end = i;
-    while (end < path.length && path[end] !== "." && path[end] !== "[") {
-      end += 1;
-    }
-    if (end > i) {
-      segments.push(path.slice(i, end));
-    }
-    i = end;
-  }
-  return segments;
-}
-function getPath(obj, path) {
-  if (!path) {
-    return obj;
-  }
-  let current = obj;
-  for (const key of pathSegments(path)) {
-    if (typeof current !== "object" || current === null) {
-      return void 0;
-    }
-    current = current[key];
-  }
-  return current;
-}
-
-// src/utils/scope-path.ts
-function resolveScopedPath(ctx, path) {
-  if (path === "$values" || path === "values") {
-    return ctx.values;
-  }
-  if (path === "$resources" || path === "resources") {
-    return ctx.resources;
-  }
-  if (path === "$row" || path === "row") {
-    return ctx.row;
-  }
-  if (path === "$item" || path === "item") {
-    return ctx.item;
-  }
-  if (path.startsWith("values.")) {
-    return getPath(ctx.values, path.replace("values.", ""));
-  }
-  if (path.startsWith("resources.")) {
-    return getPath(ctx.resources, path.replace("resources.", ""));
-  }
-  if (path.startsWith("row.")) {
-    return ctx.row === void 0 ? void 0 : getPath(ctx.row, path.replace("row.", ""));
-  }
-  if (path.startsWith("item.")) {
-    return ctx.item === void 0 ? void 0 : getPath(ctx.item, path.replace("item.", ""));
-  }
-  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.");
-}
-function resolvePathStringsInData(value, ctx) {
-  if (typeof value === "string") {
-    return isExplicitScopedPath(value) ? resolveScopedPath(ctx, value) : value;
-  }
-  if (Array.isArray(value)) {
-    return value.map((item) => resolvePathStringsInData(item, ctx));
-  }
-  if (typeof value === "object" && value !== null) {
-    const result = {};
-    for (const [key, entry] of Object.entries(value)) {
-      result[key] = resolvePathStringsInData(entry, ctx);
-    }
-    return result;
-  }
-  return value;
-}
-
 // src/conditions/evaluate.ts
 function evaluateCondition(condition, values, state, options) {
   if ((0, import_schema2.isInvokeCondition)(condition)) {
@@ -1862,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 } : {}
   });
@@ -1908,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 } : {}
   };
@@ -1962,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 } : {}
     },
@@ -2255,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();
@@ -2277,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) {
@@ -2298,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) {
@@ -2417,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 } : {}
   };
@@ -2765,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 } : {}
       })
@@ -2849,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 } : {}
     };
@@ -2857,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 } : {}
     };
@@ -2866,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 } : {}
   };
@@ -2885,9 +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, 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) {
@@ -2903,7 +3095,7 @@ function resolveApiRequestUrl(step, engine, options) {
   } else if (hasQuery) {
     queryValue = resolvePathStringsInData(step.request.query, ctx);
   } else {
-    return step.request.url;
+    return url;
   }
   if (queryValue === void 0 || queryValue === null || typeof queryValue !== "object" || Array.isArray(queryValue)) {
     throw new TypeError("api step query must resolve to an object");
@@ -2917,10 +3109,13 @@ function resolveApiRequestUrl(step, engine, options) {
   }
   const queryString = params.toString();
   if (!queryString) {
-    return step.request.url;
+    return url;
   }
-  const separator = step.request.url.includes("?") ? "&" : "?";
-  return `${step.request.url}${separator}${queryString}`;
+  const hashIndex = url.indexOf("#");
+  const base = hashIndex < 0 ? url : url.slice(0, hashIndex);
+  const hash = hashIndex < 0 ? "" : url.slice(hashIndex);
+  const separator = base.includes("?") ? "&" : "?";
+  return `${base}${separator}${queryString}${hash}`;
 }
 function toRequestBody(value, headers) {
   if (isBodyInit(value)) {
@@ -3177,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) {
@@ -3269,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();
@@ -3297,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();
@@ -3366,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();
@@ -3813,7 +4018,8 @@ var FormEngine = class {
       getPath(
         {
           values: this.values,
-          resources: this.resources
+          resources: this.resources,
+          env: this.getEnv()
         },
         path
       )
@@ -3904,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) => {
@@ -4295,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("."))
@@ -4321,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() {
@@ -4341,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() {
@@ -4543,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;
@@ -4600,7 +4811,8 @@ var FormEngine = class {
     const source = resolveScopedPath(
       {
         values: this.values,
-        resources: this.resources
+        resources: this.resources,
+        env: this.getEnv()
       },
       options.source
     );
@@ -4627,6 +4839,7 @@ var FormEngine = class {
       {
         values: this.values,
         resources: this.resources,
+        env: this.getEnv(),
         ...options?.item !== void 0 ? { item: options.item } : {}
       },
       data.source
@@ -4652,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 } : {}
         })
       );
@@ -4663,6 +4877,7 @@ var FormEngine = class {
           {
             values: this.values,
             resources: this.resources,
+            env: this.getEnv(),
             ...options?.item !== void 0 ? { item: options.item } : {}
           },
           props.from
@@ -4686,6 +4901,7 @@ var FormEngine = class {
         {
           values: this.values,
           resources: this.resources,
+          env: this.getEnv(),
           ...options?.item !== void 0 ? { item: options.item } : {}
         },
         props.from
@@ -4717,6 +4933,7 @@ var FormEngine = class {
           {
             values: this.values,
             resources: this.resources,
+            env: this.getEnv(),
             ...options?.item !== void 0 ? { item: options.item } : {}
           },
           props.titleFrom
@@ -4756,7 +4973,8 @@ var FormEngine = class {
     const source = resolveScopedPath(
       {
         values: this.values,
-        resources: this.resources
+        resources: this.resources,
+        env: this.getEnv()
       },
       props.source
     );
@@ -4945,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()
@@ -4963,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) => {
@@ -4981,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) => {
@@ -5002,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();
@@ -5203,18 +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