@lorion-org/react 1.0.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the 'Software'), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,202 @@
+# @lorion-org/react
+
+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.
+
+## Install
+
+```shell
+pnpm add @lorion-org/react react
+```
+
+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.
+
+## 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
+- a React adapter over LORION descriptor discovery and composition graph packages
+
+## What It Is Not
+
+- not a UI component library
+- not a router
+- not a package manager
+- not an application naming convention
+
+## Basic Runtime
+
+```ts
+import { CapabilityRuntimeProvider, createCapabilityRuntime } from '@lorion-org/react';
+import { capabilityModules } from 'virtual:capabilities';
+
+const capabilityRuntime = createCapabilityRuntime(capabilityModules);
+```
+
+Render the provider once around the application tree:
+
+```tsx
+import { CapabilityRuntimeProvider } from '@lorion-org/react';
+
+root.render(
+  <CapabilityRuntimeProvider runtime={capabilityRuntime}>
+    <App />
+  </CapabilityRuntimeProvider>,
+);
+```
+
+Capability contracts can define extension points and read contributions:
+
+```ts
+import { createContributionContract } from '@lorion-org/react';
+
+type Tool = {
+  id: string;
+  label: string;
+};
+
+const toolContract = createContributionContract<Tool>('tools');
+
+export function defineTools(tools: readonly Tool[]) {
+  return toolContract.define(tools);
+}
+
+export function useTools(): Tool[] {
+  return toolContract.use();
+}
+```
+
+## Capability Packages
+
+Each local capability package needs a descriptor and an activation export:
+
+```text
+capabilities/
+  my-capability/
+    capability.json
+    package.json
+    src/
+      capability.ts
+      routes/
+        index.tsx
+```
+
+```json
+{
+  "id": "my-capability",
+  "version": "1.0.0",
+  "dependencies": {
+    "other-capability": "^1.0.0"
+  }
+}
+```
+
+```json
+{
+  "name": "@my-app/my-capability",
+  "type": "module",
+  "exports": {
+    "./capability": "./src/capability.ts"
+  }
+}
+```
+
+The `src/routes` folder is optional. If present, `lorionReact()` can expose it
+to TanStack Router as a capability-owned route subtree.
+
+## Vite
+
+```ts
+import { 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`.
+
+```ts
+const capabilityComposition = {
+  selected: ['default'],
+};
+const lorion = lorionReact({
+  workspaceRoot,
+  routesDirectory,
+  ...capabilityComposition,
+});
+
+export default defineConfig({
+  plugins: [
+    lorion.capabilityLoader,
+    tanstackStart({
+      router: {
+        virtualRouteConfig: lorion.routeConfig,
+      },
+    }),
+  ],
+});
+```
+
+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.
+
+## Provider Selection
+
+Capabilities that implement another capability can declare `providesFor`:
+
+```json
+{
+  "id": "payment-provider-stripe",
+  "version": "1.0.0",
+  "providesFor": "payment-checkout"
+}
+```
+
+Any active descriptor can declare preferences with `providerPreferences`:
+
+```json
+{
+  "id": "web",
+  "version": "1.0.0",
+  "providerPreferences": {
+    "payment-checkout": "payment-provider-stripe"
+  }
+}
+```
+
+Read the resolved provider selection from the runtime:
+
+```ts
+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.
+
+## 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
+
+## Playground
+
+The package includes a React playground that mirrors the Nuxt package playground with a demo shop, checkout providers, and a tech monitor.
+
+```sh
+pnpm --filter @lorion-org/react dev:playground
+```
+
+The playground runs on `http://localhost:3200` and uses local demo capabilities under `playground/capabilities`.
+
+## Local Commands
+
+```shell
+cd packages/react
+pnpm build
+pnpm test
+pnpm typecheck
+pnpm package:check
+```

package/dist/index.cjs

@@ -0,0 +1,154 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  CapabilityRuntimeProvider: () => CapabilityRuntimeProvider,
+  createCapabilityRuntime: () => createCapabilityRuntime,
+  createContributionContract: () => createContributionContract,
+  defineCapability: () => defineCapability,
+  defineContribution: () => defineContribution,
+  defineExtensionPoint: () => defineExtensionPoint,
+  getCapabilityProviderSelection: () => getCapabilityProviderSelection,
+  useCapabilityRuntime: () => useCapabilityRuntime
+});
+module.exports = __toCommonJS(index_exports);
+var import_react = require("react");
+var import_composition_graph = require("@lorion-org/composition-graph");
+var import_provider_selection = require("@lorion-org/provider-selection");
+function defineExtensionPoint(id) {
+  return { id };
+}
+function defineContribution(extensionPoint, values) {
+  return { extensionPoint, values };
+}
+function createContributionContract(id) {
+  const extensionPoint = defineExtensionPoint(id);
+  return {
+    extensionPoint,
+    define: (values) => defineContribution(extensionPoint, values),
+    get: (runtime) => runtime.getContributions(extensionPoint),
+    use: () => useCapabilityRuntime().getContributions(extensionPoint)
+  };
+}
+function getCapabilityProviderSelection(runtime, options = {}) {
+  const descriptors = runtime.catalog.getAllDescriptors();
+  const descriptorPreferences = (0, import_provider_selection.collectProviderPreferences)({
+    items: descriptors,
+    getProviderPreferences: (descriptor) => descriptor.providerPreferences
+  });
+  const configuredProviders = {
+    ...descriptorPreferences,
+    ...options.configuredProviders ?? {}
+  };
+  const resolution = (0, import_provider_selection.resolveItemProviderSelection)({
+    items: descriptors,
+    getCapabilityId: (descriptor) => descriptor.providesFor,
+    getProviderId: (descriptor) => descriptor.id,
+    configuredProviders,
+    ...options.fallbackProviders ? { fallbackProviders: options.fallbackProviders } : {}
+  });
+  return {
+    excludedProviderIds: resolution.excludedProviderIds,
+    mismatches: resolution.mismatches,
+    selections: resolution.selections
+  };
+}
+function defineCapability(capability) {
+  if (capability.id !== capability.manifest.id) {
+    throw new Error(
+      `Capability "${capability.id}" must match capability.json id "${capability.manifest.id}".`
+    );
+  }
+  return capability;
+}
+function createCapabilityRuntime(capabilities) {
+  const enabledCapabilities = capabilities.filter(
+    (capability) => capability.manifest.disabled !== true
+  );
+  const catalog = createCapabilityCatalog(enabledCapabilities);
+  assertUniqueCapabilities(enabledCapabilities);
+  assertKnownCapabilityDependencies(enabledCapabilities, catalog);
+  const contributions = collectContributions(enabledCapabilities);
+  return {
+    capabilities: Object.freeze([...enabledCapabilities]),
+    catalog,
+    getContributions: (extensionPoint) => [...contributions.get(extensionPoint.id) ?? []]
+  };
+}
+var CapabilityRuntimeContext = (0, import_react.createContext)(null);
+function CapabilityRuntimeProvider({
+  children,
+  runtime
+}) {
+  return (0, import_react.createElement)(CapabilityRuntimeContext.Provider, { value: runtime }, children);
+}
+function useCapabilityRuntime() {
+  const runtime = (0, import_react.useContext)(CapabilityRuntimeContext);
+  if (!runtime) {
+    throw new Error("useCapabilityRuntime must be used inside CapabilityRuntimeProvider.");
+  }
+  return runtime;
+}
+function assertUniqueCapabilities(capabilities) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const capability of capabilities) {
+    if (seen.has(capability.id)) {
+      throw new Error(`Duplicate capability id "${capability.id}".`);
+    }
+    seen.add(capability.id);
+  }
+}
+function assertKnownCapabilityDependencies(capabilities, catalog) {
+  for (const capability of capabilities) {
+    (0, import_composition_graph.assertKnownDescriptorIds)(
+      catalog.getDescriptorMap(),
+      Object.keys(capability.manifest.dependencies ?? {}),
+      `capability "${capability.id}" dependencies`
+    );
+  }
+}
+function collectContributions(capabilities) {
+  const contributions = /* @__PURE__ */ new Map();
+  for (const capability of capabilities) {
+    for (const contribution of capability.contributions ?? []) {
+      const bucket = contributions.get(contribution.extensionPoint.id) ?? [];
+      bucket.push(...contribution.values);
+      contributions.set(contribution.extensionPoint.id, bucket);
+    }
+  }
+  return contributions;
+}
+function createCapabilityCatalog(capabilities) {
+  return (0, import_composition_graph.createDescriptorCatalog)({
+    descriptors: capabilities.map((capability) => capability.manifest)
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CapabilityRuntimeProvider,
+  createCapabilityRuntime,
+  createContributionContract,
+  defineCapability,
+  defineContribution,
+  defineExtensionPoint,
+  getCapabilityProviderSelection,
+  useCapabilityRuntime
+});

package/dist/index.d.cts

@@ -0,0 +1,50 @@
+import { ReactNode, ReactElement } from 'react';
+import { Descriptor, DescriptorCatalog } from '@lorion-org/composition-graph';
+import { ProviderPreferenceMap, ProviderSelectionResolution } from '@lorion-org/provider-selection';
+
+type CapabilityManifest = Descriptor & {
+    description?: string;
+    providerPreferences?: ProviderPreferenceMap;
+};
+type ExtensionPoint<T> = {
+    id: string;
+    readonly value?: T;
+};
+type CapabilityContribution<T = unknown> = {
+    extensionPoint: ExtensionPoint<T>;
+    values: readonly T[];
+};
+type RuntimeCapability = {
+    id: string;
+    manifest: CapabilityManifest;
+    contributions?: readonly CapabilityContribution[];
+};
+type CapabilityRuntime = {
+    capabilities: readonly RuntimeCapability[];
+    catalog: DescriptorCatalog;
+    getContributions: <T>(extensionPoint: ExtensionPoint<T>) => T[];
+};
+type ContributionContract<T> = {
+    define: (values: readonly T[]) => CapabilityContribution<T>;
+    extensionPoint: ExtensionPoint<T>;
+    get: (runtime: CapabilityRuntime) => T[];
+    use: () => T[];
+};
+declare function defineExtensionPoint<T>(id: string): ExtensionPoint<T>;
+declare function defineContribution<T>(extensionPoint: ExtensionPoint<T>, values: readonly T[]): CapabilityContribution<T>;
+declare function createContributionContract<T>(id: string): ContributionContract<T>;
+type CapabilityProviderSelectionOptions = {
+    configuredProviders?: ProviderPreferenceMap;
+    fallbackProviders?: ProviderPreferenceMap;
+};
+declare function getCapabilityProviderSelection(runtime: CapabilityRuntime, options?: CapabilityProviderSelectionOptions): ProviderSelectionResolution;
+declare function defineCapability(capability: RuntimeCapability): RuntimeCapability;
+declare function createCapabilityRuntime(capabilities: readonly RuntimeCapability[]): CapabilityRuntime;
+type CapabilityRuntimeProviderProps = {
+    children: ReactNode;
+    runtime: CapabilityRuntime;
+};
+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 };

package/dist/index.d.ts

@@ -0,0 +1,50 @@
+import { ReactNode, ReactElement } from 'react';
+import { Descriptor, DescriptorCatalog } from '@lorion-org/composition-graph';
+import { ProviderPreferenceMap, ProviderSelectionResolution } from '@lorion-org/provider-selection';
+
+type CapabilityManifest = Descriptor & {
+    description?: string;
+    providerPreferences?: ProviderPreferenceMap;
+};
+type ExtensionPoint<T> = {
+    id: string;
+    readonly value?: T;
+};
+type CapabilityContribution<T = unknown> = {
+    extensionPoint: ExtensionPoint<T>;
+    values: readonly T[];
+};
+type RuntimeCapability = {
+    id: string;
+    manifest: CapabilityManifest;
+    contributions?: readonly CapabilityContribution[];
+};
+type CapabilityRuntime = {
+    capabilities: readonly RuntimeCapability[];
+    catalog: DescriptorCatalog;
+    getContributions: <T>(extensionPoint: ExtensionPoint<T>) => T[];
+};
+type ContributionContract<T> = {
+    define: (values: readonly T[]) => CapabilityContribution<T>;
+    extensionPoint: ExtensionPoint<T>;
+    get: (runtime: CapabilityRuntime) => T[];
+    use: () => T[];
+};
+declare function defineExtensionPoint<T>(id: string): ExtensionPoint<T>;
+declare function defineContribution<T>(extensionPoint: ExtensionPoint<T>, values: readonly T[]): CapabilityContribution<T>;
+declare function createContributionContract<T>(id: string): ContributionContract<T>;
+type CapabilityProviderSelectionOptions = {
+    configuredProviders?: ProviderPreferenceMap;
+    fallbackProviders?: ProviderPreferenceMap;
+};
+declare function getCapabilityProviderSelection(runtime: CapabilityRuntime, options?: CapabilityProviderSelectionOptions): ProviderSelectionResolution;
+declare function defineCapability(capability: RuntimeCapability): RuntimeCapability;
+declare function createCapabilityRuntime(capabilities: readonly RuntimeCapability[]): CapabilityRuntime;
+type CapabilityRuntimeProviderProps = {
+    children: ReactNode;
+    runtime: CapabilityRuntime;
+};
+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 };

package/dist/index.js

@@ -0,0 +1,128 @@
+// src/index.ts
+import { createContext, createElement, useContext } from "react";
+import {
+  assertKnownDescriptorIds,
+  createDescriptorCatalog
+} from "@lorion-org/composition-graph";
+import {
+  collectProviderPreferences,
+  resolveItemProviderSelection
+} from "@lorion-org/provider-selection";
+function defineExtensionPoint(id) {
+  return { id };
+}
+function defineContribution(extensionPoint, values) {
+  return { extensionPoint, values };
+}
+function createContributionContract(id) {
+  const extensionPoint = defineExtensionPoint(id);
+  return {
+    extensionPoint,
+    define: (values) => defineContribution(extensionPoint, values),
+    get: (runtime) => runtime.getContributions(extensionPoint),
+    use: () => useCapabilityRuntime().getContributions(extensionPoint)
+  };
+}
+function getCapabilityProviderSelection(runtime, options = {}) {
+  const descriptors = runtime.catalog.getAllDescriptors();
+  const descriptorPreferences = collectProviderPreferences({
+    items: descriptors,
+    getProviderPreferences: (descriptor) => descriptor.providerPreferences
+  });
+  const configuredProviders = {
+    ...descriptorPreferences,
+    ...options.configuredProviders ?? {}
+  };
+  const resolution = resolveItemProviderSelection({
+    items: descriptors,
+    getCapabilityId: (descriptor) => descriptor.providesFor,
+    getProviderId: (descriptor) => descriptor.id,
+    configuredProviders,
+    ...options.fallbackProviders ? { fallbackProviders: options.fallbackProviders } : {}
+  });
+  return {
+    excludedProviderIds: resolution.excludedProviderIds,
+    mismatches: resolution.mismatches,
+    selections: resolution.selections
+  };
+}
+function defineCapability(capability) {
+  if (capability.id !== capability.manifest.id) {
+    throw new Error(
+      `Capability "${capability.id}" must match capability.json id "${capability.manifest.id}".`
+    );
+  }
+  return capability;
+}
+function createCapabilityRuntime(capabilities) {
+  const enabledCapabilities = capabilities.filter(
+    (capability) => capability.manifest.disabled !== true
+  );
+  const catalog = createCapabilityCatalog(enabledCapabilities);
+  assertUniqueCapabilities(enabledCapabilities);
+  assertKnownCapabilityDependencies(enabledCapabilities, catalog);
+  const contributions = collectContributions(enabledCapabilities);
+  return {
+    capabilities: Object.freeze([...enabledCapabilities]),
+    catalog,
+    getContributions: (extensionPoint) => [...contributions.get(extensionPoint.id) ?? []]
+  };
+}
+var CapabilityRuntimeContext = createContext(null);
+function CapabilityRuntimeProvider({
+  children,
+  runtime
+}) {
+  return createElement(CapabilityRuntimeContext.Provider, { value: runtime }, children);
+}
+function useCapabilityRuntime() {
+  const runtime = useContext(CapabilityRuntimeContext);
+  if (!runtime) {
+    throw new Error("useCapabilityRuntime must be used inside CapabilityRuntimeProvider.");
+  }
+  return runtime;
+}
+function assertUniqueCapabilities(capabilities) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const capability of capabilities) {
+    if (seen.has(capability.id)) {
+      throw new Error(`Duplicate capability id "${capability.id}".`);
+    }
+    seen.add(capability.id);
+  }
+}
+function assertKnownCapabilityDependencies(capabilities, catalog) {
+  for (const capability of capabilities) {
+    assertKnownDescriptorIds(
+      catalog.getDescriptorMap(),
+      Object.keys(capability.manifest.dependencies ?? {}),
+      `capability "${capability.id}" dependencies`
+    );
+  }
+}
+function collectContributions(capabilities) {
+  const contributions = /* @__PURE__ */ new Map();
+  for (const capability of capabilities) {
+    for (const contribution of capability.contributions ?? []) {
+      const bucket = contributions.get(contribution.extensionPoint.id) ?? [];
+      bucket.push(...contribution.values);
+      contributions.set(contribution.extensionPoint.id, bucket);
+    }
+  }
+  return contributions;
+}
+function createCapabilityCatalog(capabilities) {
+  return createDescriptorCatalog({
+    descriptors: capabilities.map((capability) => capability.manifest)
+  });
+}
+export {
+  CapabilityRuntimeProvider,
+  createCapabilityRuntime,
+  createContributionContract,
+  defineCapability,
+  defineContribution,
+  defineExtensionPoint,
+  getCapabilityProviderSelection,
+  useCapabilityRuntime
+};

package/dist/vite.cjs

@@ -0,0 +1,229 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/vite.ts
+var vite_exports = {};
+__export(vite_exports, {
+  capabilityLoader: () => capabilityLoader,
+  createCapabilityRouteConfig: () => createCapabilityRouteConfig,
+  discoverCapabilities: () => discoverCapabilities,
+  discoverSelectedCapabilities: () => discoverSelectedCapabilities,
+  lorionReact: () => lorionReact,
+  renderCapabilityModule: () => renderCapabilityModule
+});
+module.exports = __toCommonJS(vite_exports);
+var import_node_fs = require("fs");
+var import_node_path = require("path");
+var import_composition_graph = require("@lorion-org/composition-graph");
+var import_descriptor_discovery = require("@lorion-org/descriptor-discovery");
+var virtualModuleId = "virtual:capabilities";
+var resolvedVirtualModuleId = `\0${virtualModuleId}`;
+function capabilityLoader(options = {}) {
+  let config;
+  let capabilities = [];
+  return {
+    name: "lorion-react-capability-loader",
+    enforce: "pre",
+    configResolved(resolvedConfig) {
+      config = resolvedConfig;
+      capabilities = discoverSelectedCapabilities(
+        resolveWorkspaceRoot(config.root, options),
+        options
+      );
+    },
+    resolveId(id) {
+      if (id === virtualModuleId) return resolvedVirtualModuleId;
+      return capabilities.find((capability) => capability.importSpecifier === id)?.entryFile;
+    },
+    load(id) {
+      if (id !== resolvedVirtualModuleId) return null;
+      return renderCapabilityModule(capabilities);
+    }
+  };
+}
+function lorionReact(options) {
+  return {
+    capabilityLoader: capabilityLoader(options),
+    routeConfig: createCapabilityRouteConfig(options)
+  };
+}
+function discoverCapabilities(workspaceRoot, options = {}) {
+  const capabilitiesRoot = (0, import_node_path.resolve)(workspaceRoot, options.capabilitiesDir ?? "capabilities");
+  if (!(0, import_node_fs.existsSync)(capabilitiesRoot)) {
+    throw new Error(`Capabilities directory not found: ${capabilitiesRoot}`);
+  }
+  return discoverCapabilityDescriptors(workspaceRoot, options).map(discoverCapability).sort((left, right) => left.id.localeCompare(right.id));
+}
+function discoverSelectedCapabilities(workspaceRoot, options = {}) {
+  return selectCapabilities(discoverCapabilities(workspaceRoot, options), options);
+}
+function selectCapabilities(capabilities, options = {}) {
+  const enabledCapabilities = capabilities.filter((capability) => capability.disabled !== true);
+  if (!options.selected?.length && !options.baseDescriptors?.length) {
+    return [...enabledCapabilities];
+  }
+  const catalog = (0, import_composition_graph.createDescriptorCatalog)({
+    descriptors: enabledCapabilities.map((capability) => capability.manifest)
+  });
+  const selection = (0, import_composition_graph.createCompositionSelection)({
+    catalog,
+    selected: [...options.selected ?? []],
+    baseDescriptors: [...options.baseDescriptors ?? []],
+    ...options.policy ? { policy: options.policy } : {}
+  });
+  const selectedIds = new Set(selection.getResolved());
+  return enabledCapabilities.filter((capability) => selectedIds.has(capability.id));
+}
+function renderCapabilityModule(capabilities) {
+  const imports = capabilities.map(
+    (capability) => `import { capability as ${capability.variableName} } from '${capability.importSpecifier}'`
+  ).join("\n");
+  const variables = capabilities.map((capability) => `  ${capability.variableName},`).join("\n");
+  return `${imports}
+
+export const capabilityModules = [
+${variables}
+]
+`;
+}
+function createCapabilityRouteConfig(options) {
+  if (!options?.workspaceRoot) {
+    throw new Error("createCapabilityRouteConfig requires a workspaceRoot option.");
+  }
+  if (!options?.routesDirectory) {
+    throw new Error("createCapabilityRouteConfig requires a routesDirectory option.");
+  }
+  const routesDirectory = (0, import_node_path.resolve)(options.routesDirectory);
+  const capabilities = discoverSelectedCapabilities(options.workspaceRoot, options);
+  const capabilityRouteSubtrees = capabilities.filter(hasRouteDirectory).filter((capability) => capability.disabled !== true).map((capability) => ({
+    type: "physical",
+    pathPrefix: "",
+    directory: toPosixPath((0, import_node_path.relative)(routesDirectory, capability.routesDirectory))
+  }));
+  return {
+    type: "root",
+    file: "__root.tsx",
+    children: [
+      ...options.indexRouteFile === false ? [] : [
+        {
+          type: "index",
+          file: options.indexRouteFile ?? "index.tsx"
+        }
+      ],
+      ...capabilityRouteSubtrees
+    ]
+  };
+}
+function discoverCapabilityDescriptors(workspaceRoot, options) {
+  const capabilitiesDir = options.capabilitiesDir ?? "capabilities";
+  return (0, import_descriptor_discovery.discoverDescriptors)({
+    cwd: workspaceRoot,
+    descriptorPaths: [`${capabilitiesDir}/*/capability.json`],
+    validation: {
+      schema: import_descriptor_discovery.descriptorSchema
+    }
+  });
+}
+function discoverCapability(entry) {
+  const capabilityDir = entry.cwd;
+  const packagePath = (0, import_node_path.resolve)(capabilityDir, "package.json");
+  if (!(0, import_node_fs.existsSync)(packagePath)) {
+    throw new Error(
+      `Capability must define both capability.json and package.json: ${capabilityDir}`
+    );
+  }
+  const packageJson = readJson(packagePath);
+  const packageName = packageJson.name;
+  if (typeof packageName !== "string") {
+    throw new Error(`Capability package is missing "name": ${packagePath}`);
+  }
+  const activationEntry = resolveActivationEntry(capabilityDir, packageJson);
+  const routesDirectory = resolveRouteDirectory(capabilityDir);
+  return {
+    id: entry.descriptor.id,
+    disabled: entry.descriptor.disabled === true,
+    entryFile: activationEntry.entryFile,
+    importSpecifier: activationEntry.importSpecifier,
+    manifest: entry.descriptor,
+    packageName,
+    ...routesDirectory ? { routesDirectory } : {},
+    variableName: toVariableName(entry.descriptor.id)
+  };
+}
+function resolveRouteDirectory(capabilityDir) {
+  const routesDirectory = (0, import_node_path.resolve)(capabilityDir, "src", "routes");
+  return (0, import_node_fs.existsSync)(routesDirectory) ? routesDirectory : void 0;
+}
+function resolveActivationEntry(capabilityDir, packageJson) {
+  const packageName = packageJson.name;
+  const packageExports = packageJson.exports;
+  if (typeof packageName !== "string") {
+    throw new Error(
+      `Capability package is missing "name": ${(0, import_node_path.resolve)(capabilityDir, "package.json")}`
+    );
+  }
+  if (!isRecord(packageExports) || typeof packageExports["./capability"] !== "string") {
+    throw new Error(`Capability package is missing a "./capability" export: ${capabilityDir}`);
+  }
+  return {
+    entryFile: (0, import_node_path.resolve)(capabilityDir, packageExports["./capability"]),
+    importSpecifier: `${packageName}/capability`
+  };
+}
+function hasRouteDirectory(capability) {
+  return typeof capability.routesDirectory === "string";
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function resolveWorkspaceRoot(configRoot, options) {
+  if (options.workspaceRoot) return (0, import_node_path.resolve)(options.workspaceRoot);
+  return findWorkspaceRoot(configRoot);
+}
+function findWorkspaceRoot(startDir) {
+  let current = (0, import_node_path.resolve)(startDir);
+  while (true) {
+    if ((0, import_node_fs.existsSync)((0, import_node_path.join)(current, "pnpm-workspace.yaml")) && (0, import_node_fs.existsSync)((0, import_node_path.join)(current, "capabilities"))) {
+      return current;
+    }
+    const parent = (0, import_node_path.dirname)(current);
+    if (parent === current) {
+      throw new Error(`Could not find React workspace root from: ${startDir}`);
+    }
+    current = parent;
+  }
+}
+function readJson(path) {
+  return JSON.parse((0, import_node_fs.readFileSync)(path, "utf8"));
+}
+function toVariableName(name) {
+  return `${name.replace(/[^a-zA-Z0-9]+/g, " ").trim().replace(/(?:^|\s)([a-zA-Z0-9])/g, (_, char) => char.toUpperCase()).replace(/^([A-Z])/, (char) => char.toLowerCase())}Capability`;
+}
+function toPosixPath(path) {
+  return path.split(import_node_path.sep).join("/");
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  capabilityLoader,
+  createCapabilityRouteConfig,
+  discoverCapabilities,
+  discoverSelectedCapabilities,
+  lorionReact,
+  renderCapabilityModule
+});

package/dist/vite.d.cts

@@ -0,0 +1,61 @@
+import { DescriptorId, CompositionPolicy, Descriptor } from '@lorion-org/composition-graph';
+
+type CapabilityLoaderOptions = {
+    capabilitiesDir?: string;
+    baseDescriptors?: readonly DescriptorId[];
+    policy?: Partial<CompositionPolicy>;
+    selected?: readonly DescriptorId[];
+    workspaceRoot?: string;
+};
+type CapabilityRouteConfigOptions = CapabilityLoaderOptions & {
+    indexRouteFile?: false | string;
+    routesDirectory: string;
+    workspaceRoot: string;
+};
+type LorionReactViteOptions = CapabilityRouteConfigOptions;
+type LorionReactViteSetup = {
+    capabilityLoader: VitePlugin;
+    routeConfig: VirtualRootRoute;
+};
+type DiscoveredCapability = {
+    disabled: boolean;
+    entryFile: string;
+    id: string;
+    importSpecifier: string;
+    manifest: Descriptor;
+    packageName: string;
+    routesDirectory?: string;
+    variableName: string;
+};
+type VirtualIndexRoute = {
+    file: string;
+    type: 'index';
+};
+type VirtualPhysicalRouteSubtree = {
+    directory: string;
+    pathPrefix: string;
+    type: 'physical';
+};
+type VirtualRootRoute = {
+    children: Array<VirtualIndexRoute | VirtualPhysicalRouteSubtree>;
+    file: string;
+    type: 'root';
+};
+type ViteResolvedConfig = {
+    root: string;
+};
+type VitePlugin = {
+    configResolved: (resolvedConfig: ViteResolvedConfig) => void;
+    enforce: 'pre';
+    load: (id: string) => string | null;
+    name: string;
+    resolveId: (id: string) => string | undefined;
+};
+declare function capabilityLoader(options?: CapabilityLoaderOptions): VitePlugin;
+declare function lorionReact(options: LorionReactViteOptions): LorionReactViteSetup;
+declare function discoverCapabilities(workspaceRoot: string, options?: Pick<CapabilityLoaderOptions, 'capabilitiesDir'>): DiscoveredCapability[];
+declare function discoverSelectedCapabilities(workspaceRoot: string, options?: CapabilityLoaderOptions): DiscoveredCapability[];
+declare function renderCapabilityModule(capabilities: readonly DiscoveredCapability[]): string;
+declare function createCapabilityRouteConfig(options: CapabilityRouteConfigOptions): VirtualRootRoute;
+
+export { type CapabilityLoaderOptions, type CapabilityRouteConfigOptions, type DiscoveredCapability, type LorionReactViteOptions, type LorionReactViteSetup, type VirtualIndexRoute, type VirtualPhysicalRouteSubtree, type VirtualRootRoute, type VitePlugin, type ViteResolvedConfig, capabilityLoader, createCapabilityRouteConfig, discoverCapabilities, discoverSelectedCapabilities, lorionReact, renderCapabilityModule };

package/dist/vite.d.ts

@@ -0,0 +1,61 @@
+import { DescriptorId, CompositionPolicy, Descriptor } from '@lorion-org/composition-graph';
+
+type CapabilityLoaderOptions = {
+    capabilitiesDir?: string;
+    baseDescriptors?: readonly DescriptorId[];
+    policy?: Partial<CompositionPolicy>;
+    selected?: readonly DescriptorId[];
+    workspaceRoot?: string;
+};
+type CapabilityRouteConfigOptions = CapabilityLoaderOptions & {
+    indexRouteFile?: false | string;
+    routesDirectory: string;
+    workspaceRoot: string;
+};
+type LorionReactViteOptions = CapabilityRouteConfigOptions;
+type LorionReactViteSetup = {
+    capabilityLoader: VitePlugin;
+    routeConfig: VirtualRootRoute;
+};
+type DiscoveredCapability = {
+    disabled: boolean;
+    entryFile: string;
+    id: string;
+    importSpecifier: string;
+    manifest: Descriptor;
+    packageName: string;
+    routesDirectory?: string;
+    variableName: string;
+};
+type VirtualIndexRoute = {
+    file: string;
+    type: 'index';
+};
+type VirtualPhysicalRouteSubtree = {
+    directory: string;
+    pathPrefix: string;
+    type: 'physical';
+};
+type VirtualRootRoute = {
+    children: Array<VirtualIndexRoute | VirtualPhysicalRouteSubtree>;
+    file: string;
+    type: 'root';
+};
+type ViteResolvedConfig = {
+    root: string;
+};
+type VitePlugin = {
+    configResolved: (resolvedConfig: ViteResolvedConfig) => void;
+    enforce: 'pre';
+    load: (id: string) => string | null;
+    name: string;
+    resolveId: (id: string) => string | undefined;
+};
+declare function capabilityLoader(options?: CapabilityLoaderOptions): VitePlugin;
+declare function lorionReact(options: LorionReactViteOptions): LorionReactViteSetup;
+declare function discoverCapabilities(workspaceRoot: string, options?: Pick<CapabilityLoaderOptions, 'capabilitiesDir'>): DiscoveredCapability[];
+declare function discoverSelectedCapabilities(workspaceRoot: string, options?: CapabilityLoaderOptions): DiscoveredCapability[];
+declare function renderCapabilityModule(capabilities: readonly DiscoveredCapability[]): string;
+declare function createCapabilityRouteConfig(options: CapabilityRouteConfigOptions): VirtualRootRoute;
+
+export { type CapabilityLoaderOptions, type CapabilityRouteConfigOptions, type DiscoveredCapability, type LorionReactViteOptions, type LorionReactViteSetup, type VirtualIndexRoute, type VirtualPhysicalRouteSubtree, type VirtualRootRoute, type VitePlugin, type ViteResolvedConfig, capabilityLoader, createCapabilityRouteConfig, discoverCapabilities, discoverSelectedCapabilities, lorionReact, renderCapabilityModule };

package/dist/vite.js

@@ -0,0 +1,205 @@
+// src/vite.ts
+import { existsSync, readFileSync } from "fs";
+import { dirname, join, relative, resolve, sep } from "path";
+import {
+  createCompositionSelection,
+  createDescriptorCatalog
+} from "@lorion-org/composition-graph";
+import {
+  descriptorSchema,
+  discoverDescriptors
+} from "@lorion-org/descriptor-discovery";
+var virtualModuleId = "virtual:capabilities";
+var resolvedVirtualModuleId = `\0${virtualModuleId}`;
+function capabilityLoader(options = {}) {
+  let config;
+  let capabilities = [];
+  return {
+    name: "lorion-react-capability-loader",
+    enforce: "pre",
+    configResolved(resolvedConfig) {
+      config = resolvedConfig;
+      capabilities = discoverSelectedCapabilities(
+        resolveWorkspaceRoot(config.root, options),
+        options
+      );
+    },
+    resolveId(id) {
+      if (id === virtualModuleId) return resolvedVirtualModuleId;
+      return capabilities.find((capability) => capability.importSpecifier === id)?.entryFile;
+    },
+    load(id) {
+      if (id !== resolvedVirtualModuleId) return null;
+      return renderCapabilityModule(capabilities);
+    }
+  };
+}
+function lorionReact(options) {
+  return {
+    capabilityLoader: capabilityLoader(options),
+    routeConfig: createCapabilityRouteConfig(options)
+  };
+}
+function discoverCapabilities(workspaceRoot, options = {}) {
+  const capabilitiesRoot = resolve(workspaceRoot, options.capabilitiesDir ?? "capabilities");
+  if (!existsSync(capabilitiesRoot)) {
+    throw new Error(`Capabilities directory not found: ${capabilitiesRoot}`);
+  }
+  return discoverCapabilityDescriptors(workspaceRoot, options).map(discoverCapability).sort((left, right) => left.id.localeCompare(right.id));
+}
+function discoverSelectedCapabilities(workspaceRoot, options = {}) {
+  return selectCapabilities(discoverCapabilities(workspaceRoot, options), options);
+}
+function selectCapabilities(capabilities, options = {}) {
+  const enabledCapabilities = capabilities.filter((capability) => capability.disabled !== true);
+  if (!options.selected?.length && !options.baseDescriptors?.length) {
+    return [...enabledCapabilities];
+  }
+  const catalog = createDescriptorCatalog({
+    descriptors: enabledCapabilities.map((capability) => capability.manifest)
+  });
+  const selection = createCompositionSelection({
+    catalog,
+    selected: [...options.selected ?? []],
+    baseDescriptors: [...options.baseDescriptors ?? []],
+    ...options.policy ? { policy: options.policy } : {}
+  });
+  const selectedIds = new Set(selection.getResolved());
+  return enabledCapabilities.filter((capability) => selectedIds.has(capability.id));
+}
+function renderCapabilityModule(capabilities) {
+  const imports = capabilities.map(
+    (capability) => `import { capability as ${capability.variableName} } from '${capability.importSpecifier}'`
+  ).join("\n");
+  const variables = capabilities.map((capability) => `  ${capability.variableName},`).join("\n");
+  return `${imports}
+
+export const capabilityModules = [
+${variables}
+]
+`;
+}
+function createCapabilityRouteConfig(options) {
+  if (!options?.workspaceRoot) {
+    throw new Error("createCapabilityRouteConfig requires a workspaceRoot option.");
+  }
+  if (!options?.routesDirectory) {
+    throw new Error("createCapabilityRouteConfig requires a routesDirectory option.");
+  }
+  const routesDirectory = resolve(options.routesDirectory);
+  const capabilities = discoverSelectedCapabilities(options.workspaceRoot, options);
+  const capabilityRouteSubtrees = capabilities.filter(hasRouteDirectory).filter((capability) => capability.disabled !== true).map((capability) => ({
+    type: "physical",
+    pathPrefix: "",
+    directory: toPosixPath(relative(routesDirectory, capability.routesDirectory))
+  }));
+  return {
+    type: "root",
+    file: "__root.tsx",
+    children: [
+      ...options.indexRouteFile === false ? [] : [
+        {
+          type: "index",
+          file: options.indexRouteFile ?? "index.tsx"
+        }
+      ],
+      ...capabilityRouteSubtrees
+    ]
+  };
+}
+function discoverCapabilityDescriptors(workspaceRoot, options) {
+  const capabilitiesDir = options.capabilitiesDir ?? "capabilities";
+  return discoverDescriptors({
+    cwd: workspaceRoot,
+    descriptorPaths: [`${capabilitiesDir}/*/capability.json`],
+    validation: {
+      schema: descriptorSchema
+    }
+  });
+}
+function discoverCapability(entry) {
+  const capabilityDir = entry.cwd;
+  const packagePath = resolve(capabilityDir, "package.json");
+  if (!existsSync(packagePath)) {
+    throw new Error(
+      `Capability must define both capability.json and package.json: ${capabilityDir}`
+    );
+  }
+  const packageJson = readJson(packagePath);
+  const packageName = packageJson.name;
+  if (typeof packageName !== "string") {
+    throw new Error(`Capability package is missing "name": ${packagePath}`);
+  }
+  const activationEntry = resolveActivationEntry(capabilityDir, packageJson);
+  const routesDirectory = resolveRouteDirectory(capabilityDir);
+  return {
+    id: entry.descriptor.id,
+    disabled: entry.descriptor.disabled === true,
+    entryFile: activationEntry.entryFile,
+    importSpecifier: activationEntry.importSpecifier,
+    manifest: entry.descriptor,
+    packageName,
+    ...routesDirectory ? { routesDirectory } : {},
+    variableName: toVariableName(entry.descriptor.id)
+  };
+}
+function resolveRouteDirectory(capabilityDir) {
+  const routesDirectory = resolve(capabilityDir, "src", "routes");
+  return existsSync(routesDirectory) ? routesDirectory : void 0;
+}
+function resolveActivationEntry(capabilityDir, packageJson) {
+  const packageName = packageJson.name;
+  const packageExports = packageJson.exports;
+  if (typeof packageName !== "string") {
+    throw new Error(
+      `Capability package is missing "name": ${resolve(capabilityDir, "package.json")}`
+    );
+  }
+  if (!isRecord(packageExports) || typeof packageExports["./capability"] !== "string") {
+    throw new Error(`Capability package is missing a "./capability" export: ${capabilityDir}`);
+  }
+  return {
+    entryFile: resolve(capabilityDir, packageExports["./capability"]),
+    importSpecifier: `${packageName}/capability`
+  };
+}
+function hasRouteDirectory(capability) {
+  return typeof capability.routesDirectory === "string";
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function resolveWorkspaceRoot(configRoot, options) {
+  if (options.workspaceRoot) return resolve(options.workspaceRoot);
+  return findWorkspaceRoot(configRoot);
+}
+function findWorkspaceRoot(startDir) {
+  let current = resolve(startDir);
+  while (true) {
+    if (existsSync(join(current, "pnpm-workspace.yaml")) && existsSync(join(current, "capabilities"))) {
+      return current;
+    }
+    const parent = dirname(current);
+    if (parent === current) {
+      throw new Error(`Could not find React workspace root from: ${startDir}`);
+    }
+    current = parent;
+  }
+}
+function readJson(path) {
+  return JSON.parse(readFileSync(path, "utf8"));
+}
+function toVariableName(name) {
+  return `${name.replace(/[^a-zA-Z0-9]+/g, " ").trim().replace(/(?:^|\s)([a-zA-Z0-9])/g, (_, char) => char.toUpperCase()).replace(/^([A-Z])/, (char) => char.toLowerCase())}Capability`;
+}
+function toPosixPath(path) {
+  return path.split(sep).join("/");
+}
+export {
+  capabilityLoader,
+  createCapabilityRouteConfig,
+  discoverCapabilities,
+  discoverSelectedCapabilities,
+  lorionReact,
+  renderCapabilityModule
+};

package/package.json

@@ -0,0 +1,89 @@
+{
+  "name": "@lorion-org/react",
+  "version": "1.0.0-beta.1",
+  "description": "React capability runtime and Vite helpers for LORION descriptor-based applications.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lorion-org/lorion.git",
+    "directory": "packages/react"
+  },
+  "homepage": "https://github.com/lorion-org/lorion/tree/main/packages/react#readme",
+  "bugs": {
+    "url": "https://github.com/lorion-org/lorion/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./vite": {
+      "import": {
+        "types": "./dist/vite.d.ts",
+        "default": "./dist/vite.js"
+      },
+      "require": {
+        "types": "./dist/vite.d.cts",
+        "default": "./dist/vite.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@lorion-org/composition-graph": "^1.0.0-beta.1",
+    "@lorion-org/provider-selection": "^1.0.0-beta.1",
+    "@lorion-org/descriptor-discovery": "^1.0.0-beta.1"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0"
+  },
+  "devDependencies": {
+    "@tanstack/react-router": "^1.168.25",
+    "@tanstack/router-plugin": "^1.167.28",
+    "@types/node": "^22.15.17",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@vitejs/plugin-react": "^5.1.0",
+    "react-dom": "^19.0.0",
+    "typescript": "^5.8.3",
+    "vite": "^7.3.2",
+    "vitest": "^3.1.3"
+  },
+  "keywords": [
+    "lorion",
+    "react",
+    "capability",
+    "vite"
+  ],
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts src/vite.ts --format esm,cjs --dts",
+    "clean": "rimraf coverage dist tsconfig.tsbuildinfo",
+    "lint": "eslint src --ext .ts",
+    "package:check": "pnpm build && pnpm pack --dry-run && publint",
+    "build:playground": "vite build --config playground/vite.config.ts",
+    "dev:playground": "vite dev --config playground/vite.config.ts --host 0.0.0.0",
+    "test": "vitest run --root ../.. --config vitest.config.mts packages/react/src/index.spec.ts packages/react/src/vite.spec.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "typecheck:playground": "tsc -p playground/tsconfig.json --noEmit"
+  }
+}