@lorion-org/react 1.0.0-beta.1 → 1.0.0-beta.3

package/README.md

@@ -1,8 +1,15 @@
 # @lorion-org/react
 
+[![npm](https://img.shields.io/npm/v/@lorion-org/react)](https://www.npmjs.com/package/@lorion-org/react)
+[![CI](https://github.com/lorion-org/lorion/actions/workflows/ci.yml/badge.svg)](https://github.com/lorion-org/lorion/actions/workflows/ci.yml)
+
 React capability runtime and Vite helpers for LORION descriptor-based applications.
 
-Use this package when a React application is assembled from local capability packages that expose a `capability.json` descriptor and a `./capability` activation export.
+Use this package when a React application is assembled from local capability
+packages that each expose a `capability.json` descriptor. It supports two
+deliberate consumption models over the same LORION discovery and composition
+graph, and both are first-class: pick one per product (see Two Composition
+Models).
 
 ## Install
 
@@ -10,15 +17,42 @@ Use this package when a React application is assembled from local capability pac
 pnpm add @lorion-org/react react
 ```
 
+Host configs that import selection helpers from `@lorion-org/composition-graph`
+should declare that package directly too.
+
 Add Vite, TanStack Router, or another router in the host application as needed.
 The runtime helpers do not own routing; the Vite entry point only prepares
 capability discovery and TanStack-compatible virtual route config.
 
+## Quick start
+
+Add the Vite capability loader, then consume the resolved capabilities with your
+own runtime (this is the loader-only path, Model B):
+
+```ts
+// vite.config.ts
+import { capabilityLoader } from '@lorion-org/react/vite';
+
+export default defineConfig({
+  plugins: [capabilityLoader({ workspaceRoot: import.meta.dirname })],
+});
+```
+
+```ts
+// main.ts
+import { capabilityModules } from 'virtual:capabilities';
+// register the pre-resolved capabilities with your own plugin runtime
+```
+
+For a batteries-included React runtime and file-based routing instead, use
+`lorionReact()` (Model A). Both are described under Two Composition Models.
+
 ## What It Is
 
 - a small React binding for immutable capability contributions
 - a Vite virtual module helper for active capability activation exports
 - a TanStack virtual route config helper for capability-owned route folders
+- scoped public runtime config for active capabilities
 - a React adapter over LORION descriptor discovery and composition graph packages
 
 ## What It Is Not
@@ -28,7 +62,41 @@ capability discovery and TanStack-compatible virtual route config.
 - not a package manager
 - not an application naming convention
 
-## Basic Runtime
+## Two Composition Models
+
+Both models build on the same LORION discovery, composition graph, provider
+selection, and `virtual:capabilities` build output. They differ only in how much
+of the React side the host delegates to this package. Neither is a special case;
+choose one per product.
+
+### Model A: React capability runtime and routing
+
+`lorionReact()` wires the Vite capability loader, the React capability runtime
+(`createCapabilityRuntime`), and TanStack file-based route composition together.
+Capabilities activate through the `./capability` convention and own route
+folders. Use this when the product wants a batteries-included React runtime and
+file-based routing from LORION.
+
+### Model B: capability loader with your own runtime
+
+`capabilityLoader()` on its own resolves the descriptor graph at build time and
+emits `virtual:capabilities`; the host consumes that pre-resolved module list
+with its own plugin registry, its own routing, and its own lifecycle. Nothing
+from the React runtime or route config is required. Capabilities activate through
+an explicit `activation` resolver against their existing package exports, and
+dependency-only libraries stay graph-only. Use this when the product already owns
+a plugin system, or when one package set ships as several product distributions,
+and only needs LORION for selection and activation.
+
+|               | Model A                                  | Model B                                              |
+| ------------- | ---------------------------------------- | ---------------------------------------------------- |
+| Vite entry    | `lorionReact()`                          | `capabilityLoader()`                                 |
+| React runtime | `createCapabilityRuntime` (this package) | host-owned                                           |
+| Routing       | TanStack file-based via `routeConfig`    | host-owned (for example code-based)                  |
+| Activation    | `./capability` convention                | explicit `activation` resolver, graph-only otherwise |
+| Host consumes | provider and contribution contracts      | `capabilityModules` from `virtual:capabilities`      |
+
+## React Capability Runtime (Model A)
 
 ```ts
 import { CapabilityRuntimeProvider, createCapabilityRuntime } from '@lorion-org/react';
@@ -111,19 +179,19 @@ to TanStack Router as a capability-owned route subtree.
 ## Vite
 
 ```ts
-import { lorionReact } from '@lorion-org/react/vite';
+import { capabilityLoader, lorionReact } from '@lorion-org/react/vite';
 ```
 
-The Vite helper discovers `capabilities/*/capability.json`, validates the descriptor shape with LORION, resolves selected descriptors through the LORION composition graph, resolves each package `./capability` export, and exposes `virtual:capabilities`.
+`capabilityLoader` is the standalone loader used by Model B. `lorionReact()`
+bundles that loader with the Model A route config.
+
+The Vite helper discovers `capabilities/*/capability.json`, validates the descriptor shape with LORION, resolves selected descriptors through the LORION composition graph, resolves each active capability's activation entry, and exposes `virtual:capabilities`.
 
 ```ts
-const capabilityComposition = {
-  selected: ['default'],
-};
 const lorion = lorionReact({
   workspaceRoot,
   routesDirectory,
-  ...capabilityComposition,
+  defaultSelection: ['default'],
 });
 
 export default defineConfig({
@@ -138,32 +206,260 @@ export default defineConfig({
 });
 ```
 
-Route config generation stays TanStack-focused and only includes enabled, selected capability route directories. If no `selected` or `baseDescriptors` are provided, every enabled local capability remains active. Use `indexRouteFile: false` when `/` is owned by a capability route.
+By default the Vite helper reads the shared capability seed from
+`--capabilities`, `npm_config_capabilities`, and `LORION_CAPABILITIES` before it
+falls back to `defaultSelection`. No `selectionSeed.key` option is required for
+that default. Pass `selectionSeed` only to override the seed names, inject custom
+`argv`/`env` for tests, or set `selectionSeed: false` to disable CLI/env lookup.
+
+Route config generation stays TanStack-focused and only includes enabled,
+selected capability route directories. If no `selected`, seed value,
+`defaultSelection`, or `baseDescriptors` are provided, every enabled local
+capability remains active.
+Use `indexRouteFile: false` when `/` is owned by a capability route.
+
+The virtual module exports `capabilityModules`, `selectedCapabilityIds`, and
+`resolvedCapabilityIds` so host code can distinguish the seed from the final
+graph resolution.
+
+### Activation
+
+Activation binds a resolved descriptor to the module the host imports. LORION
+supports two models, chosen by the host.
+
+Convention (default): each capability activates through a `./capability` package
+export with a `capability` named export. No option is required.
+
+Explicit resolver: pass an `activation` resolver to bind against an existing
+package export, so capabilities that already expose their contribution from
+another entry point need no dedicated activation file:
+
+```ts
+capabilityLoader({
+  workspaceRoot,
+  activation: ({ descriptor }) => ({
+    exportSubpath: './web',
+    exportName: `${descriptor.id}WebPlugin`,
+  }),
+});
+```
+
+The generated import then uses the resolved subpath and export name (for example
+`import { homeWebPlugin as homeCapability } from '@scope/home/web'`), and
+specifier resolution is left to the host bundler rather than self-resolved by
+LORION.
+
+Graph-only: when the resolver returns a nullish activation for a descriptor, that
+capability still takes part in dependency resolution but activates nothing. No
+import is emitted and it never reaches `capabilityModules`. Use this for
+dependency-only libraries that shape the graph without contributing a runtime
+plugin.
+
+## Bring Your Own Runtime (Model B)
+
+In Model B the host uses only the Vite capability loader and composes the
+resolved modules with its own runtime. The build resolves the descriptor graph
+(base, selected features, transitive dependencies, and exactly one provider per
+capability) and emits `capabilityModules` already ordered and filtered.
+
+```ts
+// vite.config.ts
+capabilityLoader({
+  workspaceRoot,
+  capabilitiesDir: 'packages',
+  baseDescriptors: ['shell', 'auth'], // always-on platform base
+  defaultSelection: ['home', 'reports'], // default feature set
+  selectionSeed: { cliKeys: ['features'], envKeys: ['APP_FEATURES'] },
+  // Read a host-defined descriptor field; return undefined to keep a package
+  // graph-only. LORION descriptors carry host keys unchanged, so annotate the read.
+  activation: ({ descriptor }) =>
+    (descriptor as { surfaces?: { web?: { exportName?: string; exportSubpath?: string } } })
+      .surfaces?.web,
+});
+```
+
+To reuse the framework-free surface convention from
+[`@lorion-org/surface-activation`](../surface-activation) directly — without a
+per-host adapter — pass `surface` instead of `activation`. Pass exactly one of the
+two (passing both throws). The `fileSurfaceConvention` preset detects a surface by a
+file marker and derives its export name and import subpath (here the canonical
+`@scope/<id>/web/plugin` entry); the raw `SurfaceConvention` object stays available
+for cases the preset does not cover:
+
+```ts
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { conventionActivation, fileSurfaceConvention } from '@lorion-org/surface-activation';
+
+capabilityLoader({
+  workspaceRoot,
+  capabilitiesDir: 'packages',
+  baseDescriptors: ['shell', 'auth'],
+  defaultSelection: ['home', 'reports'],
+  surface: {
+    name: 'web',
+    resolver: conventionActivation({
+      web: fileSurfaceConvention({
+        files: ['src/web/plugin.ts'],
+        exportSuffix: 'WebPlugin',
+        exportSubpath: './web/plugin',
+        exists: existsSync, // injected — surface-activation itself touches no filesystem
+        join,
+      }),
+    }),
+  },
+});
+```
+
+Migrating from a hand-written adapter: replace
+`activation: ({ capabilityDir, descriptor }) => resolver('web', { directory: capabilityDir, id: descriptor.id })`
+with `surface: { name: 'web', resolver }`.
+
+```ts
+// main.ts: consume the pre-resolved list with your own registry
+import { capabilityModules } from 'virtual:capabilities';
+import { createRegistry } from './my-plugin-system';
+
+const registry = createRegistry();
+for (const plugin of capabilityModules) registry.register(plugin);
+await registry.setup();
+```
+
+The host runtime lists no capability by hand and makes no provider decision.
+Adding or removing a package changes only the descriptor graph, not the runtime
+wiring. Route ownership, i18n merging, and lifecycle hooks stay in the host's own
+plugin system.
+
+## Runtime Config
+
+React runtime config follows the same LORION ownership model as other
+capability data: a capability owns its config contract, deployment inputs provide
+values, and the framework adapter exposes only the safe runtime view.
+
+By default the React Vite adapter looks for:
+
+```text
+capabilities/<capability>/capability.schema.json
+.data/runtime-config/<capability>/capability.runtime.json
+```
+
+Hosts can configure the convention once:
+
+```ts
+const lorion = lorionReact({
+  workspaceRoot,
+  routesDirectory,
+  runtimeConfig: {
+    configFileName: 'capability.runtime.json',
+    schemaFileName: 'capability.schema.json',
+  },
+});
+```
+
+By default, file-backed config is read from `<workspaceRoot>/.data`. Hosts that
+need a deployment-controlled var dir can configure an env key:
+
+```ts
+const lorion = lorionReact({
+  workspaceRoot,
+  routesDirectory,
+  runtimeConfig: {
+    varDir: {
+      envKey: 'REACT_VAR_DIR',
+    },
+  },
+});
+```
+
+Runtime files use unprefixed capability-local sections:
+
+```json
+{
+  "public": {
+    "url": "https://id.example.test",
+    "realm": "demo",
+    "clientId": "web"
+  },
+  "private": {
+    "clientSecret": "server-only"
+  }
+}
+```
+
+The adapter also reads Vite env files and process env. Public keys use the
+`VITE_<CAPABILITY>_<KEY>` convention, while private keys use
+`<CAPABILITY>_<KEY>`:
+
+```text
+VITE_AUTH_OIDC_URL=https://id.example.test
+VITE_AUTH_OIDC_REALM=demo
+VITE_AUTH_OIDC_CLIENT_ID=web
+AUTH_OIDC_CLIENT_SECRET=server-only
+```
+
+Env values override runtime files. Only `public` config is emitted through
+`virtual:capability-runtime-config`; server code can opt into
+`virtual:capability-runtime-config/server`. The server virtual module is
+SSR-only and fails during client builds to prevent private config from being
+bundled.
+
+Render the config provider near the capability runtime provider:
+
+```tsx
+import { CapabilityRuntimeConfigProvider } from '@lorion-org/react';
+import { capabilityRuntimeConfig } from 'virtual:capability-runtime-config';
+
+<CapabilityRuntimeConfigProvider runtimeConfig={capabilityRuntimeConfig}>
+  <App />
+</CapabilityRuntimeConfigProvider>;
+```
+
+Capability code reads scoped public config:
+
+```ts
+import { useCapabilityRuntimeConfig } from '@lorion-org/react';
+
+const authOidc = useCapabilityRuntimeConfig('auth-oidc');
+console.log(authOidc.public.url);
+```
 
 ## Provider Selection
 
-Capabilities that implement another capability can declare `providesFor`:
+Capabilities that implement another capability can declare `providesFor`.
+Provider-owned defaults use `defaultFor` on the provider descriptor:
 
 ```json
 {
   "id": "payment-provider-stripe",
   "version": "1.0.0",
-  "providesFor": "payment-checkout"
+  "providesFor": "checkout",
+  "defaultFor": "checkout"
 }
 ```
 
-Any active descriptor can declare preferences with `providerPreferences`:
+`providesFor` and `defaultFor` both accept a string or string array. If a
+capability descriptor exists, `defaultFor` also creates the composition relation
+from that capability to the default provider.
+
+Profiles can still declare descriptor preferences with `providerPreferences`.
+Use this when the profile, not the provider package, owns the default choice:
 
 ```json
 {
   "id": "web",
   "version": "1.0.0",
   "providerPreferences": {
-    "payment-checkout": "payment-provider-stripe"
+    "checkout": "payment-provider-stripe"
   }
 }
 ```
 
+When a provider capability is explicitly selected through the normal selection
+seed, the Vite helper removes lower-priority `defaultFor` and
+`providerPreferences` relations for that capability before graph resolution.
+That selected provider wins over descriptor defaults and preferences. A losing
+provider is only present if another hard dependency still requires it.
+
 Read the resolved provider selection from the runtime:
 
 ```ts
@@ -172,24 +468,57 @@ import { getCapabilityProviderSelection } from '@lorion-org/react';
 const selection = getCapabilityProviderSelection(capabilityRuntime);
 ```
 
-Explicit `configuredProviders` passed to `getCapabilityProviderSelection()` override descriptor preferences. `fallbackProviders` are only used when no configured provider exists.
+Explicit `configuredProviders` passed to `getCapabilityProviderSelection()`
+override selected providers, provider-owned defaults, and descriptor
+preferences. `selectedProviders` can mirror the descriptor seed at runtime, and
+`fallbackProviders` are merged with descriptor defaults and only used when no
+configured or selected provider exists.
+
+The React example uses the first variant by default: Stripe declares
+`defaultFor: "checkout"` and is selected as the fallback provider. Selecting
+`web payment-provider-invoice` through the seed switches checkout to Invoice and
+leaves Stripe out of the resolved capabilities.
 
 ## API
 
 The package exposes two public entry points:
 
-- `@lorion-org/react` for runtime, contribution contracts, provider selection, and React context helpers
-- `@lorion-org/react/vite` for capability discovery, the Vite virtual module, and TanStack-compatible route config
+- `@lorion-org/react` for runtime, contribution contracts, provider selection, runtime config, and React context helpers
+- `@lorion-org/react/vite` for capability discovery, runtime-config virtual modules, and TanStack-compatible route config
+
+## Example apps
+
+Two runnable examples (at the repo root under `examples/`) demonstrate the two
+models. Both run with Lorion's `lorion-source` export condition so local
+workspace imports resolve to `src` instead of stale `dist` output.
+
+Model A, `examples/react-runtime`, mirrors the Nuxt example with a demo shop,
+checkout providers, and a tech monitor (composition runtime and file-based
+routing):
+
+```sh
+pnpm --filter @lorion-examples/react-runtime dev
+```
 
-## Playground
+It runs on `http://localhost:3200` with capabilities under
+`examples/react-runtime/capabilities`. Select a different profile or provider with
+`--capabilities=admin`, `--capabilities=web,payment-provider-invoice`, or
+`LORION_CAPABILITIES="web payment-provider-invoice"`.
 
-The package includes a React playground that mirrors the Nuxt package playground with a demo shop, checkout providers, and a tech monitor.
+Model B, `examples/react-loader`, shows the capability-loader-only path: explicit
+activation, a graph-only library, a base plus seed selection, provider selection,
+and a small hand-written registry that consumes `virtual:capabilities` with no
+LORION React runtime and no route config:
 
 ```sh
-pnpm --filter @lorion-org/react dev:playground
+pnpm --filter @lorion-examples/react-loader dev
 ```
 
-The playground runs on `http://localhost:3200` and uses local demo capabilities under `playground/capabilities`.
+It runs on `http://localhost:3201` with capabilities under
+`examples/react-loader/capabilities`. The seed replaces the default selection, while
+the base and providers resolve through the graph: switch the auth provider with
+`--features=dashboard,auth-oidc`, or change the feature set with
+`LORION_FEATURES="dashboard reports"`.
 
 ## Local Commands
 

package/dist/index.cjs

@@ -20,19 +20,62 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  CapabilityRuntimeConfigProvider: () => CapabilityRuntimeConfigProvider,
   CapabilityRuntimeProvider: () => CapabilityRuntimeProvider,
+  createCapabilityCompositionPolicy: () => import_descriptor_selection.descriptorSelectionPolicy,
   createCapabilityRuntime: () => createCapabilityRuntime,
   createContributionContract: () => createContributionContract,
+  defaultCapabilityRelationDescriptors: () => import_descriptor_selection.providerRelationDescriptors,
+  defaultCapabilityResolutionRelations: () => import_descriptor_selection.defaultResolutionRelations,
   defineCapability: () => defineCapability,
   defineContribution: () => defineContribution,
   defineExtensionPoint: () => defineExtensionPoint,
   getCapabilityProviderSelection: () => getCapabilityProviderSelection,
-  useCapabilityRuntime: () => useCapabilityRuntime
+  getCapabilityRuntimeConfig: () => getCapabilityRuntimeConfig,
+  getCapabilityRuntimeConfigScope: () => getCapabilityRuntimeConfigScope,
+  useCapabilityRuntime: () => useCapabilityRuntime,
+  useCapabilityRuntimeConfig: () => useCapabilityRuntimeConfig,
+  useCapabilityRuntimeConfigRoot: () => useCapabilityRuntimeConfigRoot,
+  useCapabilityRuntimeConfigScope: () => useCapabilityRuntimeConfigScope
 });
 module.exports = __toCommonJS(index_exports);
-var import_react = require("react");
+var import_react2 = require("react");
 var import_composition_graph = require("@lorion-org/composition-graph");
 var import_provider_selection = require("@lorion-org/provider-selection");
+
+// src/relations.ts
+var import_descriptor_selection = require("@lorion-org/descriptor-selection");
+
+// src/runtime-config.ts
+var import_react = require("react");
+var emptyRuntimeConfig = Object.freeze({ public: Object.freeze({}) });
+var CapabilityRuntimeConfigContext = (0, import_react.createContext)(emptyRuntimeConfig);
+function CapabilityRuntimeConfigProvider({
+  children,
+  runtimeConfig
+}) {
+  return (0, import_react.createElement)(CapabilityRuntimeConfigContext.Provider, { value: runtimeConfig }, children);
+}
+function useCapabilityRuntimeConfigScope(capabilityId) {
+  return getCapabilityRuntimeConfigScope(useCapabilityRuntimeConfigRoot(), capabilityId);
+}
+function useCapabilityRuntimeConfig(capabilityId) {
+  return getCapabilityRuntimeConfig(useCapabilityRuntimeConfigRoot(), capabilityId);
+}
+function useCapabilityRuntimeConfigRoot() {
+  return (0, import_react.useContext)(CapabilityRuntimeConfigContext);
+}
+function getCapabilityRuntimeConfigScope(runtimeConfig, capabilityId) {
+  const publicConfig = runtimeConfig.public[capabilityId];
+  return publicConfig && typeof publicConfig === "object" && !Array.isArray(publicConfig) ? publicConfig : {};
+}
+function getCapabilityRuntimeConfig(runtimeConfig, capabilityId) {
+  return {
+    public: getCapabilityRuntimeConfigScope(runtimeConfig, capabilityId)
+  };
+}
+
+// src/index.ts
 function defineExtensionPoint(id) {
   return { id };
 }
@@ -54,16 +97,25 @@ function getCapabilityProviderSelection(runtime, options = {}) {
     items: descriptors,
     getProviderPreferences: (descriptor) => descriptor.providerPreferences
   });
-  const configuredProviders = {
+  const providerDefaults = (0, import_provider_selection.collectProviderDefaults)({
+    items: descriptors,
+    getDefaultFor: (descriptor) => descriptor.defaultFor,
+    getProviderId: (descriptor) => descriptor.id
+  });
+  const configuredProviders = options.configuredProviders ?? {};
+  const selectedProviders = options.selectedProviders ?? {};
+  const fallbackProviders = {
+    ...providerDefaults,
     ...descriptorPreferences,
-    ...options.configuredProviders ?? {}
+    ...options.fallbackProviders ?? {}
   };
   const resolution = (0, import_provider_selection.resolveItemProviderSelection)({
     items: descriptors,
     getCapabilityId: (descriptor) => descriptor.providesFor,
     getProviderId: (descriptor) => descriptor.id,
     configuredProviders,
-    ...options.fallbackProviders ? { fallbackProviders: options.fallbackProviders } : {}
+    fallbackProviders,
+    selectedProviders
   });
   return {
     excludedProviderIds: resolution.excludedProviderIds,
@@ -93,15 +145,15 @@ function createCapabilityRuntime(capabilities) {
     getContributions: (extensionPoint) => [...contributions.get(extensionPoint.id) ?? []]
   };
 }
-var CapabilityRuntimeContext = (0, import_react.createContext)(null);
+var CapabilityRuntimeContext = (0, import_react2.createContext)(null);
 function CapabilityRuntimeProvider({
   children,
   runtime
 }) {
-  return (0, import_react.createElement)(CapabilityRuntimeContext.Provider, { value: runtime }, children);
+  return (0, import_react2.createElement)(CapabilityRuntimeContext.Provider, { value: runtime }, children);
 }
 function useCapabilityRuntime() {
-  const runtime = (0, import_react.useContext)(CapabilityRuntimeContext);
+  const runtime = (0, import_react2.useContext)(CapabilityRuntimeContext);
   if (!runtime) {
     throw new Error("useCapabilityRuntime must be used inside CapabilityRuntimeProvider.");
   }
@@ -138,17 +190,27 @@ function collectContributions(capabilities) {
 }
 function createCapabilityCatalog(capabilities) {
   return (0, import_composition_graph.createDescriptorCatalog)({
-    descriptors: capabilities.map((capability) => capability.manifest)
+    descriptors: capabilities.map((capability) => capability.manifest),
+    relationDescriptors: import_descriptor_selection.providerRelationDescriptors
   });
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  CapabilityRuntimeConfigProvider,
   CapabilityRuntimeProvider,
+  createCapabilityCompositionPolicy,
   createCapabilityRuntime,
   createContributionContract,
+  defaultCapabilityRelationDescriptors,
+  defaultCapabilityResolutionRelations,
   defineCapability,
   defineContribution,
   defineExtensionPoint,
   getCapabilityProviderSelection,
-  useCapabilityRuntime
+  getCapabilityRuntimeConfig,
+  getCapabilityRuntimeConfigScope,
+  useCapabilityRuntime,
+  useCapabilityRuntimeConfig,
+  useCapabilityRuntimeConfigRoot,
+  useCapabilityRuntimeConfigScope
 });

package/dist/index.d.cts

@@ -1,10 +1,31 @@
 import { ReactNode, ReactElement } from 'react';
 import { Descriptor, DescriptorCatalog } from '@lorion-org/composition-graph';
 import { ProviderPreferenceMap, ProviderSelectionResolution } from '@lorion-org/provider-selection';
+import { RuntimeConfigSection, RuntimeConfigValidationPolicy } from '@lorion-org/runtime-config';
+export { descriptorSelectionPolicy as createCapabilityCompositionPolicy, providerRelationDescriptors as defaultCapabilityRelationDescriptors, defaultResolutionRelations as defaultCapabilityResolutionRelations } from '@lorion-org/descriptor-selection';
+
+type CapabilityRuntimeConfig = {
+    public: Record<string, RuntimeConfigSection>;
+};
+type CapabilityRuntimeConfigFragment<T extends RuntimeConfigSection = RuntimeConfigSection> = {
+    public: T;
+};
+type CapabilityRuntimeConfigProviderProps = {
+    children: ReactNode;
+    runtimeConfig: CapabilityRuntimeConfig;
+};
+declare function CapabilityRuntimeConfigProvider({ children, runtimeConfig, }: CapabilityRuntimeConfigProviderProps): ReactElement;
+declare function useCapabilityRuntimeConfigScope<T extends RuntimeConfigSection = RuntimeConfigSection>(capabilityId: string): T;
+declare function useCapabilityRuntimeConfig<T extends RuntimeConfigSection = RuntimeConfigSection>(capabilityId: string): CapabilityRuntimeConfigFragment<T>;
+declare function useCapabilityRuntimeConfigRoot(): CapabilityRuntimeConfig;
+declare function getCapabilityRuntimeConfigScope<T extends RuntimeConfigSection = RuntimeConfigSection>(runtimeConfig: CapabilityRuntimeConfig, capabilityId: string): T;
+declare function getCapabilityRuntimeConfig<T extends RuntimeConfigSection = RuntimeConfigSection>(runtimeConfig: CapabilityRuntimeConfig, capabilityId: string): CapabilityRuntimeConfigFragment<T>;
 
 type CapabilityManifest = Descriptor & {
+    defaultFor?: string | string[];
     description?: string;
     providerPreferences?: ProviderPreferenceMap;
+    runtimeConfig?: RuntimeConfigValidationPolicy;
 };
 type ExtensionPoint<T> = {
     id: string;
@@ -36,6 +57,7 @@ declare function createContributionContract<T>(id: string): ContributionContract
 type CapabilityProviderSelectionOptions = {
     configuredProviders?: ProviderPreferenceMap;
     fallbackProviders?: ProviderPreferenceMap;
+    selectedProviders?: ProviderPreferenceMap;
 };
 declare function getCapabilityProviderSelection(runtime: CapabilityRuntime, options?: CapabilityProviderSelectionOptions): ProviderSelectionResolution;
 declare function defineCapability(capability: RuntimeCapability): RuntimeCapability;
@@ -47,4 +69,4 @@ type CapabilityRuntimeProviderProps = {
 declare function CapabilityRuntimeProvider({ children, runtime, }: CapabilityRuntimeProviderProps): ReactElement;
 declare function useCapabilityRuntime(): CapabilityRuntime;
 
-export { type CapabilityContribution, type CapabilityManifest, type CapabilityProviderSelectionOptions, type CapabilityRuntime, CapabilityRuntimeProvider, type CapabilityRuntimeProviderProps, type ContributionContract, type ExtensionPoint, type RuntimeCapability, createCapabilityRuntime, createContributionContract, defineCapability, defineContribution, defineExtensionPoint, getCapabilityProviderSelection, useCapabilityRuntime };
+export { type CapabilityContribution, type CapabilityManifest, type CapabilityProviderSelectionOptions, type CapabilityRuntime, type CapabilityRuntimeConfig, type CapabilityRuntimeConfigFragment, CapabilityRuntimeConfigProvider, type CapabilityRuntimeConfigProviderProps, CapabilityRuntimeProvider, type CapabilityRuntimeProviderProps, type ContributionContract, type ExtensionPoint, type RuntimeCapability, createCapabilityRuntime, createContributionContract, defineCapability, defineContribution, defineExtensionPoint, getCapabilityProviderSelection, getCapabilityRuntimeConfig, getCapabilityRuntimeConfigScope, useCapabilityRuntime, useCapabilityRuntimeConfig, useCapabilityRuntimeConfigRoot, useCapabilityRuntimeConfigScope };