@lorion-org/react 1.0.0-beta.2 → 1.0.0-beta.4

package/src/vite.ts

@@ -1,40 +1,80 @@
 import { existsSync, readFileSync } from 'node:fs';
-import { dirname, join, relative, resolve, sep } from 'node:path';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import process from 'node:process';
-import {
-  createCompositionSelection,
-  createDescriptorCatalog,
-  resolveDescriptorSelectionSeed,
-  type CompositionPolicy,
-  type Descriptor,
-  type DescriptorId,
-  type DescriptorSelectionSeedInput,
-  type RelationDescriptor,
+import { loadEnv } from 'vite';
+import type {
+  CompositionPolicy,
+  Descriptor,
+  DescriptorId,
+  DescriptorSelectionSeedInput,
+  RelationDescriptor,
 } from '@lorion-org/composition-graph';
 import {
   descriptorSchema,
   discoverDescriptors,
+  requirePackageName,
   type DiscoveredDescriptor,
 } from '@lorion-org/descriptor-discovery';
+import { resolveDescriptorSelection, selectDescriptors } from '@lorion-org/descriptor-selection';
 import {
-  collectSelectedProviderPreferences,
-  resolveSelectedProviderRelationPreferences,
-  type ProviderPreferenceMap,
-} from '@lorion-org/provider-selection';
+  createRuntimeConfigValidatorRegistry,
+  projectRuntimeConfigNamespaces,
+  resolveRuntimeConfigValidationMode,
+  toRuntimeConfigFragment,
+  toSnakeUpperCase,
+  type RuntimeConfigFragment,
+  type RuntimeConfigFragmentMap,
+  type RuntimeConfigSection,
+  type RuntimeConfigValidationPolicyInput,
+} from '@lorion-org/runtime-config';
 import {
-  createCapabilityCompositionPolicy,
-  defaultCapabilityRelationDescriptors,
-} from './relations';
+  loadRuntimeConfigSourceTree,
+  readJsonFile,
+  resolveRuntimeConfigSource as resolveRuntimeConfigVarDirSource,
+  type RuntimeConfigPathPatternSource,
+  type RuntimeConfigSchemaValidationErrorFormatter,
+} from '@lorion-org/runtime-config-node';
+import { capabilitySpecifier, type ActivationResolver } from '@lorion-org/surface-activation';
 
 const virtualModuleId = 'virtual:capabilities';
 const resolvedVirtualModuleId = `\0${virtualModuleId}`;
+const runtimeConfigModuleId = 'virtual:capability-runtime-config';
+const resolvedRuntimeConfigModuleId = `\0${runtimeConfigModuleId}`;
+const serverRuntimeConfigModuleId = 'virtual:capability-runtime-config/server';
+const resolvedServerRuntimeConfigModuleId = `\0${serverRuntimeConfigModuleId}`;
+const defaultRuntimeConfigFileName = 'capability.runtime.json';
+const defaultRuntimeConfigSchemaFileName = 'capability.schema.json';
+
+export type CapabilityActivationEntry = {
+  exportName?: string;
+  exportSubpath?: string;
+};
+
+// Returning a nullish activation marks the capability as graph-only: it takes
+// part in dependency resolution but activates nothing (no import is emitted).
+export type ResolveCapabilityActivation = (input: {
+  capabilityDir: string;
+  descriptor: Descriptor;
+  packageJson: Record<string, unknown>;
+  packageName: string;
+}) => CapabilityActivationEntry | null | undefined;
 
 export type CapabilityLoaderOptions = {
+  // How an active capability's activation is resolved (which module and export to
+  // import). Pass EITHER `surface` to reuse a lorion `conventionActivation` resolver
+  // for a named surface directly (no per-host adapter), OR the richer `activation`
+  // resolver that also sees the descriptor and package.json — not both. A nullish
+  // result marks the capability graph-only.
+  activation?: ResolveCapabilityActivation;
+  // Reuse a `conventionActivation` resolver (from `@lorion-org/surface-activation`)
+  // for a named surface, e.g. `{ name: 'web', resolver: conventionActivation({...}) }`.
+  surface?: { name: string; resolver: ActivationResolver };
   capabilitiesDir?: string;
   baseDescriptors?: readonly DescriptorId[];
   defaultSelection?: readonly DescriptorId[];
   policy?: Partial<CompositionPolicy>;
   relationDescriptors?: readonly RelationDescriptor[];
+  runtimeConfig?: false | ReactRuntimeConfigOptions;
   selected?: readonly DescriptorId[];
   selectionSeed?: false | CapabilitySelectionSeedOptions;
   workspaceRoot?: string;
@@ -42,6 +82,40 @@ export type CapabilityLoaderOptions = {
 
 export type CapabilitySelectionSeedOptions = Omit<DescriptorSelectionSeedInput, 'defaultValue'>;
 
+export type ReactRuntimeConfigEnvOptions = {
+  env?: Record<string, string | undefined>;
+  privatePrefix?: string;
+  publicPrefix?: string;
+};
+
+export type ReactRuntimeConfigValidationOptions = {
+  formatError?: RuntimeConfigSchemaValidationErrorFormatter;
+  policy?: RuntimeConfigValidationPolicyInput;
+  schemaFileName?: string;
+};
+
+export type ReactRuntimeConfigVarDirOptions = {
+  defaultValue?: string;
+  env?: Record<string, string | undefined>;
+  envKey?: string;
+  value?: string;
+};
+
+export type ReactRuntimeConfigOptions = {
+  configFileName?: string;
+  enabled?: boolean;
+  env?: false | ReactRuntimeConfigEnvOptions;
+  schemaFileName?: string;
+  source?: false | RuntimeConfigPathPatternSource;
+  validation?: false | ReactRuntimeConfigValidationOptions;
+  varDir?: string | ReactRuntimeConfigVarDirOptions;
+};
+
+export type ReactRuntimeConfig = {
+  private: Record<string, RuntimeConfigSection>;
+  public: Record<string, RuntimeConfigSection>;
+};
+
 export type CapabilityRouteConfigOptions = CapabilityLoaderOptions & {
   indexRouteFile?: false | string;
   routesDirectory: string;
@@ -56,10 +130,13 @@ export type LorionReactViteSetup = {
 };
 
 export type DiscoveredCapability = {
+  capabilityDir: string;
   disabled: boolean;
-  entryFile: string;
+  entryFile?: string;
+  // Absent for graph-only capabilities that resolve but do not activate.
+  exportName?: string;
   id: string;
-  importSpecifier: string;
+  importSpecifier?: string;
   manifest: Descriptor;
   packageName: string;
   routesDirectory?: string;
@@ -84,13 +161,16 @@ export type VirtualRootRoute = {
 };
 
 export type ViteResolvedConfig = {
+  env?: Record<string, string | undefined>;
+  envDir?: false | string;
+  mode?: string;
   root: string;
 };
 
 export type VitePlugin = {
   configResolved: (resolvedConfig: ViteResolvedConfig) => void;
   enforce: 'pre';
-  load: (id: string) => string | null;
+  load: (id: string, options?: { ssr?: boolean | undefined }) => string | null;
   name: string;
   resolveId: (id: string) => string | undefined;
 };
@@ -98,6 +178,7 @@ export type VitePlugin = {
 export function capabilityLoader(options: CapabilityLoaderOptions = {}): VitePlugin {
   let config: ViteResolvedConfig;
   let capabilities: DiscoveredCapability[] = [];
+  let runtimeConfig: ReactRuntimeConfig = { private: {}, public: {} };
 
   return {
     name: 'lorion-react-capability-loader',
@@ -108,13 +189,31 @@ export function capabilityLoader(options: CapabilityLoaderOptions = {}): VitePlu
         resolveWorkspaceRoot(config.root, options),
         options,
       );
+      runtimeConfig = createReactRuntimeConfig(
+        capabilities,
+        resolveWorkspaceRoot(config.root, options),
+        options.runtimeConfig,
+        config,
+      );
     },
     resolveId(id) {
       if (id === virtualModuleId) return resolvedVirtualModuleId;
+      if (id === runtimeConfigModuleId) return resolvedRuntimeConfigModuleId;
+      if (id === serverRuntimeConfigModuleId) return resolvedServerRuntimeConfigModuleId;
 
       return capabilities.find((capability) => capability.importSpecifier === id)?.entryFile;
     },
-    load(id) {
+    load(id, loadOptions) {
+      if (id === resolvedRuntimeConfigModuleId) return renderRuntimeConfigModule(runtimeConfig);
+      if (id === resolvedServerRuntimeConfigModuleId) {
+        if (!loadOptions?.ssr) {
+          throw new Error(
+            'virtual:capability-runtime-config/server may only be imported from SSR/server code.',
+          );
+        }
+
+        return renderServerRuntimeConfigModule(runtimeConfig);
+      }
       if (id !== resolvedVirtualModuleId) return null;
 
       return renderCapabilityModule(capabilities, resolveSelectionSeed(options));
@@ -122,6 +221,49 @@ export function capabilityLoader(options: CapabilityLoaderOptions = {}): VitePlu
   };
 }
 
+export function createReactRuntimeConfig(
+  capabilities: readonly DiscoveredCapability[],
+  workspaceRoot: string,
+  options: false | ReactRuntimeConfigOptions = {},
+  viteConfig: Partial<ViteResolvedConfig> = {},
+): ReactRuntimeConfig {
+  const normalizedOptions = normalizeRuntimeConfigOptions(options);
+  if (!normalizedOptions.enabled) return { private: {}, public: {} };
+
+  const runtimeEnv = resolveRuntimeConfigEnv(viteConfig, normalizedOptions.env ?? {});
+  const sourceFragments = normalizedOptions.source
+    ? loadRuntimeConfigSourceTree(
+        resolveRuntimeConfigPatternSource(workspaceRoot, normalizedOptions, runtimeEnv),
+      )
+    : new Map<string, RuntimeConfigFragment>();
+  const schemaEntries = readRuntimeConfigSchemas(capabilities, normalizedOptions.schemaFileName);
+  const envFragments =
+    normalizedOptions.env === false
+      ? new Map<string, RuntimeConfigFragment>()
+      : createRuntimeConfigEnvFragments(
+          createRuntimeConfigEnvFragmentOptions(
+            capabilities,
+            schemaEntries.schemas,
+            runtimeEnv,
+            normalizedOptions.env,
+          ),
+        );
+  const fragments = mergeRuntimeConfigFragmentMaps(sourceFragments, envFragments);
+
+  validateReactRuntimeConfig(capabilities, fragments, schemaEntries, normalizedOptions.validation);
+
+  const projected = projectRuntimeConfigNamespaces(fragments, {
+    namespaceStrategy: 'nested',
+    scopeIds: capabilities.map((capability) => capability.id),
+  });
+  const { public: publicConfig, ...privateConfig } = projected;
+
+  return {
+    public: publicConfig as Record<string, RuntimeConfigSection>,
+    private: privateConfig as Record<string, RuntimeConfigSection>,
+  };
+}
+
 export function lorionReact(options: LorionReactViteOptions): LorionReactViteSetup {
   return {
     capabilityLoader: capabilityLoader(options),
@@ -129,9 +271,28 @@ export function lorionReact(options: LorionReactViteOptions): LorionReactViteSet
   };
 }
 
+// Normalizes the activation option into a ResolveCapabilityActivation. With
+// `surface`, `resolver` is a lorion ActivationResolver (from conventionActivation)
+// resolved for that surface, so a host reuses the shared surface convention
+// directly with no adapter. Without `surface`, it is the richer `activation`
+// resolver. The two are mutually exclusive.
+function toResolveActivation(
+  options: Pick<CapabilityLoaderOptions, 'activation' | 'surface'>,
+): ResolveCapabilityActivation | undefined {
+  if (options.surface) {
+    if (options.activation) {
+      throw new Error('capabilityLoader: pass either `surface` or `activation`, not both.');
+    }
+    const { name, resolver } = options.surface;
+    return ({ capabilityDir, descriptor }) =>
+      resolver(name, { directory: capabilityDir, id: descriptor.id });
+  }
+  return options.activation;
+}
+
 export function discoverCapabilities(
   workspaceRoot: string,
-  options: Pick<CapabilityLoaderOptions, 'capabilitiesDir'> = {},
+  options: Pick<CapabilityLoaderOptions, 'activation' | 'capabilitiesDir' | 'surface'> = {},
 ): DiscoveredCapability[] {
   const capabilitiesRoot = resolve(workspaceRoot, options.capabilitiesDir ?? 'capabilities');
 
@@ -139,8 +300,9 @@ export function discoverCapabilities(
     throw new Error(`Capabilities directory not found: ${capabilitiesRoot}`);
   }
 
+  const resolveActivation = toResolveActivation(options);
   return discoverCapabilityDescriptors(workspaceRoot, options)
-    .map(discoverCapability)
+    .map((entry) => discoverCapability(entry, resolveActivation))
     .sort((left, right) => left.id.localeCompare(right.id));
 }
 
@@ -163,105 +325,39 @@ function selectCapabilities(
     | 'selectionSeed'
   > = {},
 ): DiscoveredCapability[] {
-  const enabledCapabilities = capabilities.filter((capability) => capability.disabled !== true);
-  const selected = resolveCapabilitySelectionSeed(options);
-
-  if (!selected.length && !options.baseDescriptors?.length) {
-    return [...enabledCapabilities];
-  }
-
-  const selectedProviders = collectSelectedProviderPreferences({
-    items: enabledCapabilities,
-    getCapabilityId: (capability) => capability.manifest.providesFor,
-    getProviderId: (capability) => capability.id,
-    selectedProviderIds: selected,
-  });
-  const selectionCapabilities = createProviderSelectionAwareCapabilities(
-    enabledCapabilities,
-    selectedProviders,
-  );
-  const catalog = createDescriptorCatalog({
-    descriptors: selectionCapabilities.map((capability) => capability.manifest),
-    relationDescriptors: [
-      ...defaultCapabilityRelationDescriptors,
-      ...(options.relationDescriptors ?? []),
-    ],
-  });
-  const selection = createCompositionSelection({
-    catalog,
-    selected: [...selected],
-    baseDescriptors: [...(options.baseDescriptors ?? [])],
-    policy: createCapabilityCompositionPolicy(options.policy),
-  });
-  const selectedIds = new Set(selection.getResolved());
-
-  return selectionCapabilities.filter((capability) => selectedIds.has(capability.id));
-}
-
-function createProviderSelectionAwareCapabilities(
-  capabilities: readonly DiscoveredCapability[],
-  selectedProviders: ProviderPreferenceMap,
-): DiscoveredCapability[] {
-  if (!Object.keys(selectedProviders).length) return [...capabilities];
-
-  return capabilities.map((capability) => {
-    const manifest = { ...capability.manifest };
-    const preferences = resolveSelectedProviderRelationPreferences({
-      providerId: capability.id,
-      defaultFor: manifest.defaultFor,
-      providerPreferences: manifest.providerPreferences as ProviderPreferenceMap | undefined,
-      selectedProviders,
-    });
-
-    delete manifest.defaultFor;
-    delete manifest.providerPreferences;
-
-    return {
-      ...capability,
-      manifest: {
-        ...manifest,
-        ...preferences,
-      },
-    };
+  return selectDescriptors({
+    items: capabilities,
+    getDescriptor: (capability) => capability.manifest,
+    withDescriptor: (capability, manifest) => ({ ...capability, manifest }),
+    seed: options,
+    ...(options.relationDescriptors ? { relationDescriptors: options.relationDescriptors } : {}),
+    ...(options.policy ? { policy: options.policy } : {}),
   });
 }
 
 function resolveSelectionSeed(
   options: Pick<CapabilityLoaderOptions, 'defaultSelection' | 'selected' | 'selectionSeed'>,
 ): DescriptorId[] {
-  return resolveCapabilitySelectionSeed(options);
-}
-
-function resolveCapabilitySelectionSeed(
-  options: Pick<CapabilityLoaderOptions, 'defaultSelection' | 'selected' | 'selectionSeed'>,
-): DescriptorId[] {
-  if (options.selected?.length) return [...options.selected];
-
-  if (options.selectionSeed === false) return [...(options.defaultSelection ?? [])];
-
-  const seedOptions = options.selectionSeed ?? {};
-  const selected = resolveDescriptorSelectionSeed({
-    argv: seedOptions.argv ?? process.argv,
-    env: seedOptions.env ?? process.env,
-    key: seedOptions.key ?? 'capability',
-    ...(seedOptions.cliKeys ? { cliKeys: seedOptions.cliKeys } : {}),
-    ...(seedOptions.envKeys ? { envKeys: seedOptions.envKeys } : {}),
-  });
-
-  return selected.length ? selected : [...(options.defaultSelection ?? [])];
+  return resolveDescriptorSelection(options);
 }
 
 export function renderCapabilityModule(
   capabilities: readonly DiscoveredCapability[],
   selected: readonly DescriptorId[] = [],
 ): string {
-  const imports = capabilities
+  // Only capabilities with a resolved activation entry are imported and
+  // registered. Graph-only capabilities take part in dependency resolution and
+  // still appear in resolvedCapabilityIds, but emit no import.
+  const activated = capabilities.filter(
+    (capability) => capability.exportName && capability.importSpecifier,
+  );
+  const imports = activated
     .map(
       (capability) =>
-        `import { capability as ${capability.variableName} } from '${capability.importSpecifier}'`,
+        `import { ${capability.exportName} as ${capability.variableName} } from '${capability.importSpecifier}'`,
     )
     .join('\n');
-  const variables = capabilities.map((capability) => `  ${capability.variableName},`).join('\n');
+  const variables = activated.map((capability) => `  ${capability.variableName},`).join('\n');
   const capabilityIds = capabilities.map((capability) => capability.id);
 
   return `${imports}
@@ -276,6 +372,18 @@ ${variables}
 `;
 }
 
+export function renderRuntimeConfigModule(runtimeConfig: ReactRuntimeConfig): string {
+  return `export const capabilityRuntimeConfig = ${JSON.stringify({ public: runtimeConfig.public })}
+
+export const publicCapabilityRuntimeConfig = capabilityRuntimeConfig.public
+`;
+}
+
+export function renderServerRuntimeConfigModule(runtimeConfig: ReactRuntimeConfig): string {
+  return `export const capabilityServerRuntimeConfig = ${JSON.stringify(runtimeConfig)}
+`;
+}
+
 export function createCapabilityRouteConfig(
   options: CapabilityRouteConfigOptions,
 ): VirtualRootRoute {
@@ -330,7 +438,10 @@ function discoverCapabilityDescriptors(
   });
 }
 
-function discoverCapability(entry: DiscoveredDescriptor): DiscoveredCapability {
+function discoverCapability(
+  entry: DiscoveredDescriptor,
+  resolveActivation?: ResolveCapabilityActivation,
+): DiscoveredCapability {
   const capabilityDir = entry.cwd;
   const packagePath = resolve(capabilityDir, 'package.json');
 
@@ -341,27 +452,350 @@ function discoverCapability(entry: DiscoveredDescriptor): DiscoveredCapability {
   }
 
   const packageJson = readJson(packagePath);
-  const packageName = packageJson.name;
+  const packageName = requirePackageName(packageJson, packagePath);
 
-  if (typeof packageName !== 'string') {
-    throw new Error(`Capability package is missing "name": ${packagePath}`);
-  }
-
-  const activationEntry = resolveActivationEntry(capabilityDir, packageJson);
+  const activationEntry = resolveActivationEntry(
+    capabilityDir,
+    packageJson,
+    packageName,
+    entry.descriptor,
+    resolveActivation,
+  );
   const routesDirectory = resolveRouteDirectory(capabilityDir);
 
   return {
+    capabilityDir,
     id: entry.descriptor.id,
     disabled: entry.descriptor.disabled === true,
-    entryFile: activationEntry.entryFile,
-    importSpecifier: activationEntry.importSpecifier,
     manifest: entry.descriptor,
     packageName,
+    ...(activationEntry
+      ? {
+          exportName: activationEntry.exportName,
+          importSpecifier: activationEntry.importSpecifier,
+          ...(activationEntry.entryFile ? { entryFile: activationEntry.entryFile } : {}),
+        }
+      : {}),
     ...(routesDirectory ? { routesDirectory } : {}),
     variableName: toVariableName(entry.descriptor.id),
   };
 }
 
+type NormalizedReactRuntimeConfigOptions = {
+  configFileName: string;
+  enabled: boolean;
+  env: false | ReactRuntimeConfigEnvOptions;
+  schemaFileName: string;
+  source?: RuntimeConfigPathPatternSource;
+  validation: false | ReactRuntimeConfigValidationOptions;
+  varDir?: string | ReactRuntimeConfigVarDirOptions;
+};
+
+type RuntimeConfigSchemaEntries = {
+  paths: Map<string, string>;
+  schemas: Record<string, object>;
+};
+
+function normalizeRuntimeConfigOptions(
+  options: false | ReactRuntimeConfigOptions,
+): NormalizedReactRuntimeConfigOptions {
+  if (options === false) {
+    return {
+      configFileName: defaultRuntimeConfigFileName,
+      enabled: false,
+      env: false,
+      schemaFileName: defaultRuntimeConfigSchemaFileName,
+      validation: false,
+    };
+  }
+
+  const configFileName = options.configFileName ?? defaultRuntimeConfigFileName;
+
+  return {
+    configFileName,
+    enabled: options.enabled !== false,
+    env: options.env ?? {},
+    schemaFileName: options.schemaFileName ?? defaultRuntimeConfigSchemaFileName,
+    ...(options.source === false
+      ? {}
+      : {
+          source: options.source ?? { paths: [] },
+        }),
+    validation: options.validation === false ? false : (options.validation ?? {}),
+    ...(options.varDir ? { varDir: options.varDir } : {}),
+  };
+}
+
+function resolveRuntimeConfigPatternSource(
+  workspaceRoot: string,
+  options: Pick<NormalizedReactRuntimeConfigOptions, 'configFileName' | 'source' | 'varDir'>,
+  env: Record<string, string | undefined>,
+): RuntimeConfigPathPatternSource {
+  if (!options.source?.paths.length) {
+    const varDir = resolveRuntimeConfigVarDir(workspaceRoot, options.varDir, env);
+
+    return {
+      paths: [join(varDir, 'runtime-config', '*', options.configFileName)],
+    };
+  }
+
+  return {
+    paths: options.source.paths.map((entry: string) =>
+      isAbsolute(entry) ? entry : resolve(workspaceRoot, entry),
+    ),
+  };
+}
+
+function resolveRuntimeConfigVarDir(
+  workspaceRoot: string,
+  options: string | ReactRuntimeConfigVarDirOptions | undefined,
+  env: Record<string, string | undefined>,
+): string {
+  const rawVarDir =
+    typeof options === 'string'
+      ? options
+      : resolveRuntimeConfigVarDirSource({
+          defaultVarDir: resolve(workspaceRoot, '.data'),
+          env: options?.env ?? env,
+          envKey: options?.envKey ?? 'RUNTIME_CONFIG_VAR_DIR',
+          ...(options?.value ? { varDir: options.value } : {}),
+          ...(options?.defaultValue ? { defaultVarDir: options.defaultValue } : {}),
+        }).varDir;
+
+  return isAbsolute(rawVarDir) ? rawVarDir : resolve(workspaceRoot, rawVarDir);
+}
+
+function resolveRuntimeConfigEnv(
+  viteConfig: Partial<ViteResolvedConfig>,
+  options: ReactRuntimeConfigEnvOptions | false,
+): Record<string, string | undefined> {
+  if (options === false) return {};
+  if (options.env) return options.env;
+
+  const mode = viteConfig.mode ?? process.env.NODE_ENV ?? 'development';
+  const envDir =
+    typeof viteConfig.envDir === 'string' ? viteConfig.envDir : (viteConfig.root ?? process.cwd());
+
+  return {
+    ...loadEnv(mode, envDir, ''),
+    ...process.env,
+    ...(viteConfig.env ?? {}),
+  };
+}
+
+function readRuntimeConfigSchemas(
+  capabilities: readonly DiscoveredCapability[],
+  schemaFileName: string,
+): RuntimeConfigSchemaEntries {
+  const paths = new Map<string, string>();
+  const schemas: Record<string, object> = {};
+
+  for (const capability of capabilities) {
+    const schemaPath = resolve(capability.capabilityDir, schemaFileName);
+    const schema = readJsonFile<object>(schemaPath, {
+      onParseError: (error, filePath) => {
+        throw new Error(`RuntimeConfig schema JSON parse error in "${filePath}": ${String(error)}`);
+      },
+    });
+
+    if (!schema) continue;
+
+    paths.set(capability.id, schemaPath);
+    schemas[capability.id] = schema;
+  }
+
+  return { paths, schemas };
+}
+
+function isJsonSchemaObject(value: unknown): value is { properties?: Record<string, unknown> } {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function getRuntimeConfigSchemaSectionKeys(
+  schema: object | undefined,
+  visibility: string,
+): string[] {
+  if (!isJsonSchemaObject(schema)) return [];
+
+  const section = schema.properties?.[visibility];
+  if (!isJsonSchemaObject(section) || !isJsonSchemaObject(section.properties)) return [];
+
+  return Object.keys(section.properties).sort();
+}
+
+function createRuntimeConfigEnvKey(input: {
+  key: string;
+  prefix?: string;
+  scopeId: string;
+}): string {
+  return toSnakeUpperCase([input.prefix, input.scopeId, input.key].filter(Boolean).join('_'));
+}
+
+function createRuntimeConfigEnvFragments(input: {
+  capabilities: readonly DiscoveredCapability[];
+  env: Record<string, string | undefined>;
+  privatePrefix?: string;
+  publicPrefix?: string;
+  schemas: Record<string, object>;
+}): RuntimeConfigFragmentMap {
+  const fragments: RuntimeConfigFragmentMap = new Map();
+
+  for (const capability of input.capabilities) {
+    const schema = input.schemas[capability.id];
+    const publicConfig: RuntimeConfigSection = {};
+    const privateConfig: RuntimeConfigSection = {};
+
+    for (const key of getRuntimeConfigSchemaSectionKeys(schema, 'public')) {
+      const envKey = createRuntimeConfigEnvKey({
+        key,
+        prefix: input.publicPrefix ?? 'VITE',
+        scopeId: capability.id,
+      });
+      const value = input.env[envKey];
+
+      if (value !== undefined) publicConfig[key] = value;
+    }
+
+    for (const key of getRuntimeConfigSchemaSectionKeys(schema, 'private')) {
+      const envKey = createRuntimeConfigEnvKey({
+        key,
+        scopeId: capability.id,
+        ...(input.privatePrefix !== undefined ? { prefix: input.privatePrefix } : {}),
+      });
+      const value = input.env[envKey];
+
+      if (value !== undefined) privateConfig[key] = value;
+    }
+
+    if (Object.keys(publicConfig).length || Object.keys(privateConfig).length) {
+      fragments.set(capability.id, {
+        ...(Object.keys(publicConfig).length ? { public: publicConfig } : {}),
+        ...(Object.keys(privateConfig).length ? { private: privateConfig } : {}),
+      });
+    }
+  }
+
+  return fragments;
+}
+
+function createRuntimeConfigEnvFragmentOptions(
+  capabilities: readonly DiscoveredCapability[],
+  schemas: Record<string, object>,
+  env: Record<string, string | undefined>,
+  options: ReactRuntimeConfigEnvOptions,
+): Parameters<typeof createRuntimeConfigEnvFragments>[0] {
+  return {
+    capabilities,
+    env,
+    ...(options.privatePrefix !== undefined ? { privatePrefix: options.privatePrefix } : {}),
+    ...(options.publicPrefix !== undefined ? { publicPrefix: options.publicPrefix } : {}),
+    schemas,
+  };
+}
+
+function mergeRuntimeConfigSections(
+  left: RuntimeConfigSection | undefined,
+  right: RuntimeConfigSection | undefined,
+): RuntimeConfigSection | undefined {
+  const section = {
+    ...(left ?? {}),
+    ...(right ?? {}),
+  };
+
+  return Object.keys(section).length ? section : undefined;
+}
+
+function mergeRuntimeConfigFragment(
+  left: RuntimeConfigFragment | undefined,
+  right: RuntimeConfigFragment | undefined,
+): RuntimeConfigFragment {
+  const publicConfig = mergeRuntimeConfigSections(left?.public, right?.public);
+  const privateConfig = mergeRuntimeConfigSections(left?.private, right?.private);
+
+  return toRuntimeConfigFragment({
+    ...(publicConfig ? { public: publicConfig } : {}),
+    ...(privateConfig ? { private: privateConfig } : {}),
+  });
+}
+
+function mergeRuntimeConfigFragmentMaps(
+  left: RuntimeConfigFragmentMap,
+  right: RuntimeConfigFragmentMap,
+): RuntimeConfigFragmentMap {
+  const fragments: RuntimeConfigFragmentMap = new Map(left);
+
+  for (const [scopeId, config] of right.entries()) {
+    fragments.set(scopeId, mergeRuntimeConfigFragment(fragments.get(scopeId), config));
+  }
+
+  return fragments;
+}
+
+function getCapabilityRuntimeConfigPolicy(
+  capability: DiscoveredCapability,
+  validation: ReactRuntimeConfigValidationOptions,
+): RuntimeConfigValidationPolicyInput {
+  return (
+    (capability.manifest.runtimeConfig as RuntimeConfigValidationPolicyInput | undefined) ??
+    validation.policy ??
+    'optional'
+  );
+}
+
+function shouldValidateRuntimeConfigFragment(input: {
+  capability: DiscoveredCapability;
+  fragment: RuntimeConfigFragment | undefined;
+  schema: object | undefined;
+  validation: ReactRuntimeConfigValidationOptions;
+}): boolean {
+  if (!input.schema) return false;
+
+  const mode = resolveRuntimeConfigValidationMode(
+    getCapabilityRuntimeConfigPolicy(input.capability, input.validation),
+  );
+
+  if (mode === 'none' || mode === 'onUse') return false;
+  if (mode === 'startup') return true;
+
+  return Boolean(input.fragment);
+}
+
+function validateReactRuntimeConfig(
+  capabilities: readonly DiscoveredCapability[],
+  fragments: RuntimeConfigFragmentMap,
+  schemas: RuntimeConfigSchemaEntries,
+  validation: false | ReactRuntimeConfigValidationOptions,
+): void {
+  if (validation === false) return;
+
+  const registry = createRuntimeConfigValidatorRegistry(schemas.schemas, {
+    ...(validation.formatError
+      ? {
+          formatError: (target, validationError) =>
+            validation.formatError!(
+              {
+                configPath: `${target.scopeId} runtime config`,
+                schemaPath: schemas.paths.get(target.scopeId) ?? '',
+                scopeId: target.scopeId,
+              },
+              validationError,
+            ),
+        }
+      : {}),
+  });
+
+  for (const capability of capabilities) {
+    const fragment = fragments.get(capability.id);
+    const schema = schemas.schemas[capability.id];
+
+    if (!shouldValidateRuntimeConfigFragment({ capability, fragment, schema, validation })) {
+      continue;
+    }
+
+    registry.assert(capability.id, fragment ?? {});
+  }
+}
+
 function resolveRouteDirectory(capabilityDir: string): string | undefined {
   const routesDirectory = resolve(capabilityDir, 'src', 'routes');
 
@@ -371,24 +805,36 @@ function resolveRouteDirectory(capabilityDir: string): string | undefined {
 function resolveActivationEntry(
   capabilityDir: string,
   packageJson: Record<string, unknown>,
-): { entryFile: string; importSpecifier: string } {
-  const packageName = packageJson.name;
-  const packageExports = packageJson.exports;
+  packageName: string,
+  descriptor: Descriptor,
+  resolveActivation?: ResolveCapabilityActivation,
+): { entryFile?: string; exportName: string; importSpecifier: string } | null {
+  // Without a custom activation resolver the default convention stays strict:
+  // the package must declare a string "./capability" export that LORION
+  // self-resolves to a local file.
+  if (!resolveActivation) {
+    const packageExports = packageJson.exports;
+
+    if (!isRecord(packageExports) || typeof packageExports['./capability'] !== 'string') {
+      throw new Error(`Capability package is missing a "./capability" export: ${capabilityDir}`);
+    }
 
-  if (typeof packageName !== 'string') {
-    throw new Error(
-      `Capability package is missing "name": ${resolve(capabilityDir, 'package.json')}`,
-    );
+    return {
+      entryFile: resolve(capabilityDir, packageExports['./capability']),
+      exportName: 'capability',
+      importSpecifier: capabilitySpecifier(packageName, './capability'),
+    };
   }
 
-  if (!isRecord(packageExports) || typeof packageExports['./capability'] !== 'string') {
-    throw new Error(`Capability package is missing a "./capability" export: ${capabilityDir}`);
-  }
+  // A custom resolver may target any package export and leaves specifier
+  // resolution to the host bundler. A nullish result marks a graph-only
+  // capability: resolved for the dependency graph, but not activated.
+  const activation = resolveActivation({ capabilityDir, descriptor, packageJson, packageName });
+  if (!activation) return null;
 
-  return {
-    entryFile: resolve(capabilityDir, packageExports['./capability']),
-    importSpecifier: `${packageName}/capability`,
-  };
+  const exportName = activation.exportName ?? 'capability';
+  const exportSubpath = activation.exportSubpath ?? './capability';
+  return { exportName, importSpecifier: capabilitySpecifier(packageName, exportSubpath) };
 }
 
 function hasRouteDirectory(