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

package/README.md

@@ -19,6 +19,9 @@ variants, optional providers, or profile-based feature sets.
 pnpm add @lorion-org/nuxt
 ```
 
+Host configs that import selection helpers from `@lorion-org/composition-graph`
+should declare that package directly too.
+
 ## What it is
 
 - a Nuxt 4 adapter for LORION layer orchestration
@@ -108,11 +111,10 @@ src/
   runtime-config.ts
   runtime-config-node.ts
   types.ts
-examples/
+snippets/
   read-runtime-config.server.ts
   runtime-config-source.nuxt.config.ts
   selected-extensions.nuxt.config.ts
-playground/
 test/
   fixtures/
   unit/
@@ -122,10 +124,11 @@ test/
 - `src/extensions.ts` contains descriptor discovery, selection, bootstrap, and extension-owned runtime config.
 - `src/runtime-config.ts` contains universal runtime-config adapter helpers.
 - `src/runtime-config-node.ts` contains Node-only source loading helpers.
-- The published package exports only the root Nuxt module. Runtime-config composables are generated and auto-imported by the module.
-- `examples/` contains Nuxt-focused config and server-route snippets.
-- `playground/` is a runnable Nuxt app for manual module development.
+- The published package exports the root Nuxt module, runtime-config subpaths, the descriptor schema, and runtime-safe extension helpers under `@lorion-org/nuxt/extensions`. Runtime-config composables are generated and auto-imported by the module.
+- `snippets/` contains Nuxt-focused config and server-route snippets.
+- The runnable Nuxt example app lives at `examples/nuxt` in the repo root.
 - `test/fixtures/` contains Nuxt applications used by end-to-end tests, and `test/unit/` contains package unit tests.
+- The `srvx` devDependency is load-bearing for development only: it aligns this package's dev-time `nuxt` peer context with the standalone `examples/nuxt` app (which pulls `srvx` transitively through the Nitro server). Without it, pnpm resolves `nuxt` into two peer contexts and the `nuxt/schema` module augmentation in `src/types.ts` no longer typechecks. It is not imported by any source file — do not remove it as "unused". The root `package.json` `pnpm.overrides` pins `srvx` to one version workspace-wide so this alignment cannot silently drift when Nitro bumps its own `srvx` range; bump both together if Nitro ever requires a newer `srvx`.
 
 ## Nuxt module
 
@@ -182,16 +185,23 @@ config object and public values below `runtimeConfig.public`. Set
 `privateOutput: 'section'` when the target runtime should keep private values
 below `runtimeConfig.private`.
 
-The module also auto-imports runtime-config composables unless
-`runtimeConfig.imports` is `false`.
+The module also auto-imports runtime-config composables when
+`runtimeConfig.imports` is `true`, or when it is omitted and the host Nuxt app
+keeps import scanning enabled. Hosts that set `imports.scan: false` can import
+the generated composables explicitly instead:
 
 ```ts
+import { usePublicRuntimeConfigScope } from '#build/lorion/runtime-config-composables';
+
 const checkout = usePublicRuntimeConfigScope('checkout');
 
 checkout.successPath;
 // => '/orders/confirmed'
 ```
 
+Nitro server plugins can import from
+`#internal/lorion-runtime-config-composables.mjs`.
+
 Configured module options such as `contextOutputKey` and `privateOutput` are
 used by these composables automatically.
 
@@ -296,9 +306,26 @@ export default defineNuxtConfig({
 });
 ```
 
-Applications that want CLI or env driven selection should normalize those
-inputs locally and pass the resulting seed ids through `options.selected`.
-The LORION bootstrap only receives canonical selection ids and resolves the graph.
+Applications that want CLI or env driven selection can use the shared
+capability seed directly. By default the Nuxt bootstrap reads `--capabilities`,
+`npm_config_capabilities`, and `LORION_CAPABILITIES` before falling back to
+`defaultSelection`.
+
+```ts
+const extensionBootstrap = createNuxtExtensionBootstrap({
+  rootDir: __dirname,
+  options: {
+    defaultSelection: 'default',
+  },
+});
+```
+
+No `selectionSeed.key` option is required for the default capability seed. Pass
+`selectionSeed` only when the host needs to override the seed names, inject
+custom `argv`/`env` for tests, or set `selectionSeed: false` to disable CLI/env
+lookup.
+
+The LORION bootstrap receives canonical selection ids and resolves the graph.
 
 ## Provider Selection
 
@@ -308,25 +335,38 @@ Provider extensions can declare the capability they implement:
 {
   "id": "payment-provider-stripe",
   "version": "1.0.0",
-  "providesFor": "payment-checkout"
+  "providesFor": "checkout",
+  "defaultFor": "checkout"
 }
 ```
 
+`providesFor` and `defaultFor` both accept a string or string array. Use
+`defaultFor` when the provider package owns the normal/default provider choice.
+If a descriptor exists for that capability, the Nuxt bootstrap also treats
+`defaultFor` as a composition relation from the capability to the provider.
+
 The module writes a public `providerSelection` object with selected providers,
-candidates, excluded providers, configured providers, and mismatches. Profiles
-can declare provider preferences in descriptor metadata:
+candidates, excluded providers, configured providers, fallback providers, and
+mismatches. Profiles can declare provider preferences in descriptor metadata
+when the profile owns the default choice:
 
 ```json
 {
   "id": "checkout-profile",
   "version": "1.0.0",
   "providerPreferences": {
-    "payment-checkout": "payment-provider-invoice"
+    "checkout": "payment-provider-invoice"
   }
 }
 ```
 
-Module options can still override the selected provider when a host app needs a
+If a provider descriptor is explicitly selected through the normal selection
+seed, that provider wins for its capability over descriptor preferences and
+`defaultFor` relations. This affects composition resolution too: a losing
+provider is not activated only because it declared `defaultFor`, unless another
+hard dependency still pulls it into the graph.
+
+Module options override the selected provider when a host app needs a
 deployment-specific choice:
 
 ```ts
@@ -339,7 +379,7 @@ export default defineNuxtConfig({
         extensionBootstrap,
         providers: {
           configuredProviders: {
-            'payment-checkout': 'payment-provider-invoice',
+            checkout: 'payment-provider-invoice',
           },
         },
       },
@@ -348,6 +388,10 @@ export default defineNuxtConfig({
 });
 ```
 
+Hosts that resolve provider choices outside the extension bootstrap can pass
+`providers.selectedProviders`; `providers.configuredProviders` remains the
+higher-priority deployment override.
+
 ## Runtime Config
 
 Runtime-config projection does not require extension discovery. It can be used
@@ -418,54 +462,62 @@ export default defineNuxtConfig({
 });
 ```
 
-Nuxt-focused example snippets live in [`examples/`](./examples):
+Nuxt-focused snippets live in [`snippets/`](./snippets):
 
-- [`selected-extensions.nuxt.config.ts`](./examples/selected-extensions.nuxt.config.ts)
-- [`runtime-config-source.nuxt.config.ts`](./examples/runtime-config-source.nuxt.config.ts)
-- [`read-runtime-config.server.ts`](./examples/read-runtime-config.server.ts)
+- [`selected-extensions.nuxt.config.ts`](./snippets/selected-extensions.nuxt.config.ts)
+- [`runtime-config-source.nuxt.config.ts`](./snippets/runtime-config-source.nuxt.config.ts)
+- [`read-runtime-config.server.ts`](./snippets/read-runtime-config.server.ts)
 
-## Playground
+## Example app
 
-Run the local playground from this package:
+The runnable Nuxt example lives at `examples/nuxt` (repo root). Run it from the
+workspace root:
 
 ```shell
-pnpm dev:playground
+pnpm --filter @lorion-examples/nuxt dev
 ```
 
-Select a playground composition by passing `extensions.selected` in Nuxt config:
+It runs with Lorion's `lorion-source` export condition so workspace imports
+resolve to `src` instead of stale `dist` output. Select a composition through the
+seed CLI or environment:
 
-The playground uses the module with no manual extension list in `nuxt.config.ts`.
+```shell
+pnpm --filter @lorion-examples/nuxt dev -- --capabilities=web,payment-provider-invoice
+LORION_CAPABILITIES="web payment-provider-invoice" pnpm --filter @lorion-examples/nuxt dev
+```
+
+The example app uses the module with no manual extension list in `nuxt.config.ts`.
 It configures only the presentation-specific descriptor paths, loads runtime
 config from `.runtimeconfig`, and registers the selected extension profile as
 Nuxt layers.
 
-The playground intentionally overrides the default extension root to make the
+The example app intentionally overrides the default extension root to make the
 demo concept visible:
 
 ```ts
-import LorionNuxtModule from '../src/module';
+import LorionNuxtModule, {
+  createNuxtExtensionBootstrap,
+  createNuxtExtensionLayerPaths,
+} from '@lorion-org/nuxt';
 
-export default defineNuxtConfig({
-  modules: [LorionNuxtModule],
-  lorion: {
-    extensions: {
-      defaultSelection: 'default',
-      descriptorPaths: ['layer-extensions/*/extension.json'],
-      selected: 'default',
-    },
-    providers: {
-      configuredProviders: {
-        'payment-checkout': 'payment-provider-stripe',
-      },
-    },
+const extensionBootstrap = createNuxtExtensionBootstrap({
+  rootDir: __dirname,
+  options: {
+    defaultSelection: 'default',
+    descriptorPaths: ['layer-extensions/*/extension.json'],
   },
 });
+
+export default defineNuxtConfig({
+  extends: createNuxtExtensionLayerPaths(extensionBootstrap),
+  modules: [[LorionNuxtModule, { extensionBootstrap, logging: true }]],
+});
 ```
 
-The playground shape is:
+The example app shape is:
 
 ```text
-playground/
+examples/nuxt/
   app/
   layer-extensions/
     bundles/
@@ -482,7 +534,7 @@ playground/
     runtime-config/
 ```
 
-The root app lives under `playground/app`. It owns normal Nuxt application
+The root app lives under `examples/nuxt/app`. It owns normal Nuxt application
 code. The `shops` layer extension provides the shop home route at `/`, the tiny
 Registry Hub plugin backed by `@lorion-org/registry-hub`, and the shop registry
 item type. Shop extensions depend on `shops`, register small shop entries
@@ -491,33 +543,36 @@ routes. The `admin` layer extension provides the admin home route at
 `/` for admin profiles. The technical integration monitor lives at `/tech`.
 
 The default profile points to a neutral `web` profile. It starts the shop home
-with both payment-provider extensions mounted as candidates. The playground
-config selects Stripe through `lorion.providers.configuredProviders`, and
-`@lorion-org/provider-selection` publishes the selected provider. `admin` starts
-the admin home without loading the shop or payment-provider extensions.
+with Stripe as the checkout provider because the Stripe provider descriptor
+declares `defaultFor: "checkout"`. Selecting `web payment-provider-invoice`
+overrides that default and leaves Stripe out of the resolved graph. `admin`
+starts the admin home without loading the shop or payment-provider extensions.
 
-To run variants side by side, select the profile in playground config and pass
-different Nuxt ports:
+To run variants side by side, select the seed on the CLI and pass different
+Nuxt ports:
 
 ```shell
-pnpm dev:playground -- --port 3037
-pnpm dev:playground -- --port 3039
+pnpm --filter @lorion-examples/nuxt dev -- --port 3037
+pnpm --filter @lorion-examples/nuxt dev -- --port 3039
+pnpm --filter @lorion-examples/nuxt dev -- --capabilities=admin --port 3041
+pnpm --filter @lorion-examples/nuxt dev -- --capabilities=web,payment-provider-invoice --port 3043
 ```
 
 Each extension contributes only the Nuxt layer content it needs. The module
-registers selected extensions as Nuxt layers; the playground does not list them
+registers selected extensions as Nuxt layers; the example app does not list them
 in `nuxt.config.ts`.
 Provider extensions contribute checkout pages, register a small checkout
 provider implementation through the payments layer interface, and expose server
-routes. They declare `providesFor: "payment-checkout"`, while the Nuxt module
-options provide the selected preference. Runtime config for checkout, payments,
-and providers is loaded from
+routes. They declare `providesFor: "checkout"`; Stripe additionally
+declares `defaultFor: "checkout"` so the example app demonstrates the
+provider-owned default pattern. Runtime config for checkout, payments, and
+providers is loaded from
 `.runtimeconfig/runtime-config/<scope>/runtime.config.json`.
 
 The module also exposes a public `extensionSelection` runtime-config object with
 the selected profile, resolved descriptors, and active layer extension ids. The
 module exposes a public `providerSelection` object with the selected provider,
-candidate providers, selection mode, and excluded providers. The playground reads
+candidate providers, selection mode, and excluded providers. The example app reads
 those objects on `/tech` and its demo API returns a minimal view of them from
 `/api/demo/overview`.
 
@@ -532,7 +587,7 @@ Demo extensions:
 - `payment-provider-stripe`
 - `payment-provider-invoice`
 
-The playground also shows how the wider package set can work together:
+The example app also shows how the wider package set can work together:
 
 - `@lorion-org/descriptor-discovery` discovers `extension.json` files.
 - `@lorion-org/composition-graph` resolves selected profiles to active extensions.
@@ -550,7 +605,7 @@ The package has three test groups:
 
 - unit tests for the adapter helpers and explicit extension activation
 - an end-to-end Nuxt fixture that starts a real Nuxt app with the module
-- typechecked TypeScript examples through the workspace examples check
+- typechecked TypeScript snippets through the workspace snippets check
 
 The e2e fixture verifies that `lorion.runtimeConfig` writes values into Nuxt
 runtime config, that a server route can read them back through
@@ -566,7 +621,5 @@ pnpm test
 pnpm test:unit
 pnpm test:e2e
 pnpm typecheck
-pnpm typecheck:playground
-pnpm build:playground
 pnpm package:check
 ```

package/dist/descriptor-schema.js

@@ -21,8 +21,19 @@ var extension_descriptor_schema_default = {
         },
         version: { $ref: "#/$defs/semver" },
         providesFor: {
-          type: "string",
-          minLength: 1
+          oneOf: [
+            {
+              type: "string",
+              minLength: 1
+            },
+            {
+              type: "array",
+              items: {
+                type: "string",
+                minLength: 1
+              }
+            }
+          ]
         },
         capabilities: {
           type: "array",
@@ -34,6 +45,21 @@ var extension_descriptor_schema_default = {
         dependencies: { $ref: "#/$defs/dependencyMap" },
         disabled: { type: "boolean" },
         location: { type: "string" },
+        defaultFor: {
+          oneOf: [
+            {
+              type: "string",
+              minLength: 1
+            },
+            {
+              type: "array",
+              items: {
+                type: "string",
+                minLength: 1
+              }
+            }
+          ]
+        },
         providerPreferences: {
           type: "object",
           additionalProperties: {
@@ -45,6 +71,16 @@ var extension_descriptor_schema_default = {
           type: "object",
           additionalProperties: true
         },
+        runtimeConfig: {
+          type: "object",
+          properties: {
+            validation: {
+              type: "string",
+              enum: ["none", "optional", "startup", "onUse"]
+            }
+          },
+          additionalProperties: false
+        },
         bundles: {
           type: "array",
           items: { $ref: "#/$defs/extension" }

package/dist/{extensions-vNob6d2x.d.ts → extensions-DlFRz22Q.d.ts}

@@ -1,8 +1,8 @@
-import { Descriptor, RelationDescriptor, DescriptorCatalog } from '@lorion-org/composition-graph';
+import { Descriptor, RelationDescriptor, DescriptorSelectionSeedInput, DescriptorCatalog } from '@lorion-org/composition-graph';
 import { ProviderPreferenceMap, ProviderSelection } from '@lorion-org/provider-selection';
-import { JsonSchemaObject } from '@lorion-org/descriptor-discovery';
-import { RuntimeConfigSection, ProjectSectionedRuntimeConfigOptions, RuntimeConfigFragmentMap, NamedRuntimeConfigFragment, RuntimeConfigFragment, SectionedRuntimeConfig } from '@lorion-org/runtime-config';
+import { RuntimeConfigSection, ProjectSectionedRuntimeConfigOptions, RuntimeConfigFragmentMap, NamedRuntimeConfigFragment, RuntimeConfigFragment, SectionedRuntimeConfig, RuntimeConfigValidationPolicy } from '@lorion-org/runtime-config';
 import { RuntimeConfigPathPatternSource, ValidateRuntimeConfigPatternSourceScopesOptions } from '@lorion-org/runtime-config-node';
+import { JsonSchemaObject } from './descriptor-schema.js';
 
 type RuntimeConfigNuxtFragmentInput = RuntimeConfigFragment & Record<string, unknown>;
 type RuntimeConfigNuxtFragments = RuntimeConfigFragmentMap | NamedRuntimeConfigFragment[] | Record<string, RuntimeConfigNuxtFragmentInput>;
@@ -36,10 +36,13 @@ type NuxtRuntimeConfigValidationOptions = Pick<ValidateRuntimeConfigPatternSourc
 type NuxtProviderSelectionModuleOptions = {
     configuredProviders?: ProviderPreferenceMap;
     enabled?: boolean;
+    fallbackProviders?: ProviderPreferenceMap;
+    selectedProviders?: ProviderPreferenceMap;
 };
 type NuxtProviderSelectionRuntimeConfig = {
     configuredProviders: ProviderPreferenceMap;
     excludedProviderIds: string[];
+    fallbackProviders: ProviderPreferenceMap;
     mismatches: Array<{
         capabilityId: string;
         configuredProviderId: string;
@@ -64,6 +67,7 @@ type NuxtBaseExtensionSelectionInput = {
     selectedExtensions: string[];
 };
 type NuxtBaseExtensionSelection = string | string[] | ((input: NuxtBaseExtensionSelectionInput) => string[]);
+type NuxtExtensionSelectionSeedOptions = Omit<DescriptorSelectionSeedInput, 'defaultValue'>;
 type NuxtExtensionModuleOptions = {
     baseExtensions?: NuxtBaseExtensionSelection;
     defaultSelection?: string | string[];
@@ -72,6 +76,7 @@ type NuxtExtensionModuleOptions = {
     enabled?: boolean;
     relationDescriptors?: RelationDescriptor[];
     selected?: string | string[];
+    selectionSeed?: false | NuxtExtensionSelectionSeedOptions;
 };
 type LorionNuxtModuleOptions = {
     extensionBootstrap?: NuxtExtensionBootstrap;
@@ -89,8 +94,10 @@ declare module 'nuxt/schema' {
 }
 
 type NuxtExtensionDescriptor = Descriptor & {
+    defaultFor?: string | string[];
     providerPreferences?: ProviderPreferenceMap;
     publicRuntimeConfig?: NuxtRuntimeConfig['public'];
+    runtimeConfig?: RuntimeConfigValidationPolicy;
 };
 type NuxtExtensionEntry = {
     appDir?: string;
@@ -117,6 +124,19 @@ declare function resolveExtensionSelection(input?: {
     defaultSelection?: string | string[];
     selected?: string | string[];
 }): string[];
+declare function discoverNuxtExtensionEntries(input: {
+    projectRootDir: string;
+    options: NuxtExtensionModuleOptions;
+}): NuxtExtensionEntry[];
+declare function createNuxtExtensionCatalog(input: {
+    entries: NuxtExtensionEntry[];
+    relationDescriptors?: RelationDescriptor[];
+}): DescriptorCatalog;
+declare function createNuxtExtensionEntryMap(entries: NuxtExtensionEntry[]): Map<string, NuxtExtensionEntry>;
+declare function createNuxtSelectedProviderPreferences(input: {
+    entries: NuxtExtensionEntry[];
+    selectedExtensions: string[];
+}): ProviderPreferenceMap;
 declare function createNuxtExtensionBootstrap(input: {
     options?: NuxtExtensionModuleOptions;
     rootDir: string;
@@ -124,4 +144,4 @@ declare function createNuxtExtensionBootstrap(input: {
 declare function createNuxtExtensionLayerPaths(bootstrap: NuxtExtensionBootstrap): string[];
 declare function createNuxtProviderSelectionRuntimeConfig(extensions: NuxtExtensionEntry[], options?: NuxtProviderSelectionOptions): NuxtRuntimeConfig;
 
-export { type CreateNuxtRuntimeConfigOptions as C, type LorionNuxtModuleOptions as L, type NuxtExtensionBootstrap as N, type RuntimeConfigNuxtModuleOptions as R, type NuxtRuntimeConfig as a, type NuxtExtensionBootstrapLogEvent as b, type NuxtBaseExtensionSelection as c, type NuxtBaseExtensionSelectionInput as d, type NuxtExtensionBootstrapReporter as e, type NuxtExtensionDescriptor as f, type NuxtExtensionEntry as g, type NuxtExtensionModuleOptions as h, type NuxtProviderSelectionModuleOptions as i, type NuxtProviderSelectionRuntimeConfig as j, createNuxtExtensionBootstrap as k, createNuxtExtensionLayerPaths as l, createNuxtProviderSelectionRuntimeConfig as m, type RuntimeConfigNuxtSourceOptions as n, type NuxtRuntimeConfigInput as o, type ReadNuxtRuntimeConfigOptions as p, type NuxtExtensionSelection as q, resolveExtensionSelection as r, type RuntimeConfigNuxtFragments as s, type NuxtExtensionSelectionRuntimeConfig as t, type NuxtPrivateRuntimeConfigMode as u };
+export { type CreateNuxtRuntimeConfigOptions as C, type LorionNuxtModuleOptions as L, type NuxtExtensionBootstrap as N, type RuntimeConfigNuxtModuleOptions as R, type NuxtRuntimeConfig as a, type NuxtExtensionBootstrapLogEvent as b, type NuxtBaseExtensionSelection as c, type NuxtBaseExtensionSelectionInput as d, type NuxtExtensionBootstrapReporter as e, type NuxtExtensionDescriptor as f, type NuxtExtensionEntry as g, type NuxtExtensionModuleOptions as h, type NuxtExtensionSelectionSeedOptions as i, type NuxtProviderSelectionModuleOptions as j, type NuxtProviderSelectionRuntimeConfig as k, createNuxtExtensionBootstrap as l, createNuxtExtensionCatalog as m, createNuxtExtensionEntryMap as n, createNuxtExtensionLayerPaths as o, createNuxtProviderSelectionRuntimeConfig as p, discoverNuxtExtensionEntries as q, resolveExtensionSelection as r, type RuntimeConfigNuxtSourceOptions as s, type NuxtRuntimeConfigInput as t, type ReadNuxtRuntimeConfigOptions as u, type NuxtExtensionSelection as v, type RuntimeConfigNuxtFragments as w, type NuxtExtensionSelectionRuntimeConfig as x, type NuxtPrivateRuntimeConfigMode as y, createNuxtSelectedProviderPreferences as z };

package/dist/extensions.d.ts

@@ -0,0 +1,6 @@
+import '@lorion-org/composition-graph';
+import '@lorion-org/provider-selection';
+import '@lorion-org/runtime-config';
+export { L as LorionNuxtModuleOptions, N as NuxtExtensionBootstrap, f as NuxtExtensionDescriptor, g as NuxtExtensionEntry, h as NuxtExtensionModuleOptions, i as NuxtExtensionSelectionSeedOptions, R as RuntimeConfigNuxtModuleOptions, l as createNuxtExtensionBootstrap, m as createNuxtExtensionCatalog, n as createNuxtExtensionEntryMap, o as createNuxtExtensionLayerPaths, p as createNuxtProviderSelectionRuntimeConfig, z as createNuxtSelectedProviderPreferences, q as discoverNuxtExtensionEntries, r as resolveExtensionSelection } from './extensions-DlFRz22Q.js';
+import '@lorion-org/runtime-config-node';
+import './descriptor-schema.js';