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

package/README.md

@@ -111,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/
@@ -126,9 +125,10 @@ test/
 - `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 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.
-- `examples/` contains Nuxt-focused config and server-route snippets.
-- `playground/` is a runnable Nuxt app for manual module development.
+- `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
 
@@ -462,36 +462,36 @@ 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
 ```
 
-The playground scripts run with Lorion's `lorion-source` export condition so
-local workspace package imports resolve to `src` instead of stale `dist` output.
-
-Select a playground composition through the seed CLI or environment:
+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:
 
 ```shell
-pnpm dev:playground -- --capabilities=web,payment-provider-invoice
-LORION_CAPABILITIES="web payment-provider-invoice" pnpm dev:playground
+pnpm --filter @lorion-examples/nuxt dev -- --capabilities=web,payment-provider-invoice
+LORION_CAPABILITIES="web payment-provider-invoice" pnpm --filter @lorion-examples/nuxt dev
 ```
 
-The playground uses the module with no manual extension list in `nuxt.config.ts`.
+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
@@ -514,10 +514,10 @@ export default defineNuxtConfig({
 });
 ```
 
-The playground shape is:
+The example app shape is:
 
 ```text
-playground/
+examples/nuxt/
   app/
   layer-extensions/
     bundles/
@@ -534,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
@@ -552,19 +552,19 @@ 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 dev:playground -- --capabilities=admin --port 3041
-pnpm dev:playground -- --capabilities=web,payment-provider-invoice --port 3043
+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: "checkout"`; Stripe additionally
-declares `defaultFor: "checkout"` so the playground demonstrates the
+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`.
@@ -572,7 +572,7 @@ providers is loaded from
 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`.
 
@@ -587,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.
@@ -605,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
@@ -621,7 +621,5 @@ pnpm test
 pnpm test:unit
 pnpm test:e2e
 pnpm typecheck
-pnpm typecheck:playground
-pnpm build:playground
 pnpm package:check
 ```

package/dist/extensions.js

@@ -12,9 +12,14 @@ import {
   collectProviderDefaults,
   collectProviderPreferences,
   collectSelectedProviderPreferences,
-  resolveItemProviderSelection,
-  resolveSelectedProviderRelationPreferences
+  resolveItemProviderSelection
 } from "@lorion-org/provider-selection";
+import {
+  applyProviderSelection,
+  assertSingleDefaultProvider,
+  descriptorSelectionPolicy,
+  providerRelationDescriptors
+} from "@lorion-org/descriptor-selection";
 
 // src/extension-descriptor.schema.json
 var extension_descriptor_schema_default = {
@@ -120,23 +125,6 @@ var defaultExtensionOptions = {
   descriptorPaths: ["extensions/*/extension.json"]
 };
 var defaultExtensionSelectionSeedKey = "capability";
-var defaultExtensionResolutionRelations = [
-  "dependencies",
-  "defaultProviders",
-  "providerPreferences"
-];
-var defaultNuxtRelationDescriptors = [
-  {
-    direction: "incoming",
-    field: "defaultFor",
-    id: "defaultProviders"
-  },
-  {
-    id: "providerPreferences",
-    field: "providerPreferences",
-    targetMode: "values"
-  }
-];
 function isRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -231,7 +219,7 @@ function discoverNuxtExtensionEntries(input) {
 function createNuxtExtensionCatalog(input) {
   return createDescriptorCatalog({
     descriptors: input.entries.map((entry) => entry.descriptor),
-    relationDescriptors: [...defaultNuxtRelationDescriptors, ...input.relationDescriptors ?? []]
+    relationDescriptors: [...providerRelationDescriptors, ...input.relationDescriptors ?? []]
   });
 }
 function createNuxtExtensionEntryMap(entries) {
@@ -248,27 +236,6 @@ function createNuxtSelectedProviderPreferences(input) {
     selectedProviderIds: input.selectedExtensions
   });
 }
-function createProviderSelectionAwareEntries(entries, selectedProviders) {
-  if (!Object.keys(selectedProviders).length) return entries;
-  return entries.map((entry) => {
-    const descriptor = { ...entry.descriptor };
-    const preferences = resolveSelectedProviderRelationPreferences({
-      providerId: entry.descriptor.id,
-      defaultFor: entry.descriptor.defaultFor,
-      providerPreferences: entry.descriptor.providerPreferences,
-      selectedProviders
-    });
-    delete descriptor.defaultFor;
-    delete descriptor.providerPreferences;
-    return {
-      ...entry,
-      descriptor: {
-        ...descriptor,
-        ...preferences
-      }
-    };
-  });
-}
 function mergeRuntimeConfigSection(target = {}, source = {}) {
   const merged = { ...target };
   for (const [key, value] of Object.entries(source)) {
@@ -344,19 +311,17 @@ function createNuxtExtensionBootstrap(input) {
       selectedExtensions
     };
   }
-  const selectedProviders = createNuxtSelectedProviderPreferences({
-    entries,
-    selectedExtensions
+  assertSingleDefaultProvider(entries.map((entry) => entry.descriptor));
+  const resolutionEntries = applyProviderSelection({
+    items: entries,
+    selected: selectedExtensions,
+    getDescriptor: (entry) => entry.descriptor,
+    withDescriptor: (entry, descriptor) => ({ ...entry, descriptor })
   });
-  const resolutionEntries = createProviderSelectionAwareEntries(entries, selectedProviders);
   const catalog = createCatalog(resolutionEntries);
   const selection = catalog.resolveSelection({
     baseDescriptors: baseExtensionIds,
-    policy: {
-      inspectionRelationIds: defaultExtensionResolutionRelations,
-      provenanceRelationIds: defaultExtensionResolutionRelations,
-      resolutionRelationIds: defaultExtensionResolutionRelations
-    },
+    policy: descriptorSelectionPolicy(),
     selected: selectedExtensions
   });
   const resolvedExtensionIds = selection.getResolved();

package/dist/index.js

@@ -26,9 +26,14 @@ import {
   collectProviderDefaults,
   collectProviderPreferences,
   collectSelectedProviderPreferences,
-  resolveItemProviderSelection,
-  resolveSelectedProviderRelationPreferences
+  resolveItemProviderSelection
 } from "@lorion-org/provider-selection";
+import {
+  applyProviderSelection,
+  assertSingleDefaultProvider,
+  descriptorSelectionPolicy,
+  providerRelationDescriptors
+} from "@lorion-org/descriptor-selection";
 
 // src/extension-descriptor.schema.json
 var extension_descriptor_schema_default = {
@@ -134,23 +139,6 @@ var defaultExtensionOptions = {
   descriptorPaths: ["extensions/*/extension.json"]
 };
 var defaultExtensionSelectionSeedKey = "capability";
-var defaultExtensionResolutionRelations = [
-  "dependencies",
-  "defaultProviders",
-  "providerPreferences"
-];
-var defaultNuxtRelationDescriptors = [
-  {
-    direction: "incoming",
-    field: "defaultFor",
-    id: "defaultProviders"
-  },
-  {
-    id: "providerPreferences",
-    field: "providerPreferences",
-    targetMode: "values"
-  }
-];
 function isRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -245,7 +233,7 @@ function discoverNuxtExtensionEntries(input) {
 function createNuxtExtensionCatalog(input) {
   return createDescriptorCatalog({
     descriptors: input.entries.map((entry) => entry.descriptor),
-    relationDescriptors: [...defaultNuxtRelationDescriptors, ...input.relationDescriptors ?? []]
+    relationDescriptors: [...providerRelationDescriptors, ...input.relationDescriptors ?? []]
   });
 }
 function createNuxtExtensionEntryMap(entries) {
@@ -262,27 +250,6 @@ function createNuxtSelectedProviderPreferences(input) {
     selectedProviderIds: input.selectedExtensions
   });
 }
-function createProviderSelectionAwareEntries(entries, selectedProviders) {
-  if (!Object.keys(selectedProviders).length) return entries;
-  return entries.map((entry) => {
-    const descriptor = { ...entry.descriptor };
-    const preferences = resolveSelectedProviderRelationPreferences({
-      providerId: entry.descriptor.id,
-      defaultFor: entry.descriptor.defaultFor,
-      providerPreferences: entry.descriptor.providerPreferences,
-      selectedProviders
-    });
-    delete descriptor.defaultFor;
-    delete descriptor.providerPreferences;
-    return {
-      ...entry,
-      descriptor: {
-        ...descriptor,
-        ...preferences
-      }
-    };
-  });
-}
 function mergeRuntimeConfigSection(target = {}, source = {}) {
   const merged = { ...target };
   for (const [key, value] of Object.entries(source)) {
@@ -358,19 +325,17 @@ function createNuxtExtensionBootstrap(input) {
       selectedExtensions
     };
   }
-  const selectedProviders = createNuxtSelectedProviderPreferences({
-    entries,
-    selectedExtensions
+  assertSingleDefaultProvider(entries.map((entry) => entry.descriptor));
+  const resolutionEntries = applyProviderSelection({
+    items: entries,
+    selected: selectedExtensions,
+    getDescriptor: (entry) => entry.descriptor,
+    withDescriptor: (entry, descriptor) => ({ ...entry, descriptor })
   });
-  const resolutionEntries = createProviderSelectionAwareEntries(entries, selectedProviders);
   const catalog = createCatalog(resolutionEntries);
   const selection = catalog.resolveSelection({
     baseDescriptors: baseExtensionIds,
-    policy: {
-      inspectionRelationIds: defaultExtensionResolutionRelations,
-      provenanceRelationIds: defaultExtensionResolutionRelations,
-      resolutionRelationIds: defaultExtensionResolutionRelations
-    },
+    policy: descriptorSelectionPolicy(),
     selected: selectedExtensions
   });
   const resolvedExtensionIds = selection.getResolved();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lorion-org/nuxt",
-  "version": "1.0.0-beta.2",
+  "version": "1.0.0-beta.3",
   "description": "Nuxt module for LORION libraries and framework adapters.",
   "license": "MIT",
   "repository": {
@@ -68,7 +68,6 @@
   },
   "files": [
     "dist",
-    "examples",
     "LICENSE",
     "src/**/*.ts",
     "src/**/*.json",
@@ -84,11 +83,12 @@
     "node": "^20.19.0 || >=22.12.0"
   },
   "dependencies": {
-    "@lorion-org/composition-graph": "^1.0.0-beta.2",
-    "@lorion-org/descriptor-discovery": "^1.0.0-beta.2",
+    "@lorion-org/descriptor-selection": "^1.0.0-beta.3",
+    "@lorion-org/provider-selection": "^1.0.0-beta.2",
     "@lorion-org/runtime-config": "^1.0.0-beta.1",
     "@lorion-org/runtime-config-node": "^1.0.0-beta.1",
-    "@lorion-org/provider-selection": "^1.0.0-beta.2"
+    "@lorion-org/composition-graph": "^1.0.0-beta.2",
+    "@lorion-org/descriptor-discovery": "^1.0.0-beta.3"
   },
   "peerDependencies": {
     "@nuxt/kit": "^4.0.0",
@@ -99,6 +99,7 @@
     "@nuxt/schema": "^4.4.2",
     "@nuxt/test-utils": "^3.23.0",
     "nuxt": "^4.4.2",
+    "srvx": "^0.11.15",
     "@lorion-org/registry-hub": "^1.0.0-beta.2"
   },
   "scripts": {
@@ -109,9 +110,6 @@
     "test": "pnpm test:unit && pnpm test:e2e",
     "test:unit": "vitest run --config test/vitest.unit.config.mts",
     "test:e2e": "vitest run --config test/vitest.e2e.config.mts",
-    "build:playground": "node ../../tools/run-source-condition.mjs nuxi build playground",
-    "dev:playground": "node ../../tools/run-source-condition.mjs nuxi dev playground",
-    "typecheck:playground": "node ../../tools/run-source-condition.mjs nuxi typecheck playground",
     "typecheck": "tsc -p tsconfig.json --noEmit"
   }
 }

package/src/extensions.ts

@@ -15,9 +15,14 @@ import {
   collectProviderPreferences,
   collectSelectedProviderPreferences,
   resolveItemProviderSelection,
-  resolveSelectedProviderRelationPreferences,
   type ProviderPreferenceMap,
 } from '@lorion-org/provider-selection';
+import {
+  applyProviderSelection,
+  assertSingleDefaultProvider,
+  descriptorSelectionPolicy,
+  providerRelationDescriptors,
+} from '@lorion-org/descriptor-selection';
 import type { RuntimeConfigValidationPolicy } from '@lorion-org/runtime-config';
 import type {
   NuxtBaseExtensionSelectionInput,
@@ -79,23 +84,6 @@ const defaultExtensionOptions = {
   descriptorPaths: ['extensions/*/extension.json'],
 } as const;
 const defaultExtensionSelectionSeedKey = 'capability';
-const defaultExtensionResolutionRelations = [
-  'dependencies',
-  'defaultProviders',
-  'providerPreferences',
-];
-const defaultNuxtRelationDescriptors: RelationDescriptor[] = [
-  {
-    direction: 'incoming',
-    field: 'defaultFor',
-    id: 'defaultProviders',
-  },
-  {
-    id: 'providerPreferences',
-    field: 'providerPreferences',
-    targetMode: 'values',
-  },
-];
 
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
@@ -243,7 +231,7 @@ export function createNuxtExtensionCatalog(input: {
 }): DescriptorCatalog {
   return createDescriptorCatalog({
     descriptors: input.entries.map((entry) => entry.descriptor),
-    relationDescriptors: [...defaultNuxtRelationDescriptors, ...(input.relationDescriptors ?? [])],
+    relationDescriptors: [...providerRelationDescriptors, ...(input.relationDescriptors ?? [])],
   });
 }
 
@@ -262,6 +250,9 @@ function pickEntriesById(
     .filter((entry): entry is NuxtExtensionEntry => Boolean(entry));
 }
 
+// The capability -> selected-provider map, used by the module to expose provider
+// selection through runtime config. The selection cleaning itself is delegated to
+// @lorion-org/descriptor-selection's `applyProviderSelection`.
 export function createNuxtSelectedProviderPreferences(input: {
   entries: NuxtExtensionEntry[];
   selectedExtensions: string[];
@@ -274,34 +265,6 @@ export function createNuxtSelectedProviderPreferences(input: {
   });
 }
 
-function createProviderSelectionAwareEntries(
-  entries: NuxtExtensionEntry[],
-  selectedProviders: ProviderPreferenceMap,
-): NuxtExtensionEntry[] {
-  if (!Object.keys(selectedProviders).length) return entries;
-
-  return entries.map((entry) => {
-    const descriptor = { ...entry.descriptor };
-    const preferences = resolveSelectedProviderRelationPreferences({
-      providerId: entry.descriptor.id,
-      defaultFor: entry.descriptor.defaultFor,
-      providerPreferences: entry.descriptor.providerPreferences,
-      selectedProviders,
-    });
-
-    delete descriptor.defaultFor;
-    delete descriptor.providerPreferences;
-
-    return {
-      ...entry,
-      descriptor: {
-        ...descriptor,
-        ...preferences,
-      },
-    };
-  });
-}
-
 function mergeRuntimeConfigSection(
   target: NuxtRuntimeConfig['public'] = {},
   source: NuxtRuntimeConfig['public'] = {},
@@ -405,19 +368,18 @@ export function createNuxtExtensionBootstrap(input: {
     };
   }
 
-  const selectedProviders = createNuxtSelectedProviderPreferences({
-    entries,
-    selectedExtensions,
+  assertSingleDefaultProvider(entries.map((entry) => entry.descriptor));
+
+  const resolutionEntries = applyProviderSelection({
+    items: entries,
+    selected: selectedExtensions,
+    getDescriptor: (entry) => entry.descriptor,
+    withDescriptor: (entry, descriptor) => ({ ...entry, descriptor }),
   });
-  const resolutionEntries = createProviderSelectionAwareEntries(entries, selectedProviders);
   const catalog = createCatalog(resolutionEntries);
   const selection = catalog.resolveSelection({
     baseDescriptors: baseExtensionIds,
-    policy: {
-      inspectionRelationIds: defaultExtensionResolutionRelations,
-      provenanceRelationIds: defaultExtensionResolutionRelations,
-      resolutionRelationIds: defaultExtensionResolutionRelations,
-    },
+    policy: descriptorSelectionPolicy(),
     selected: selectedExtensions,
   });
   const resolvedExtensionIds = selection.getResolved();

package/examples/read-runtime-config.server.ts

@@ -1,3 +0,0 @@
-export default defineEventHandler(() => {
-  return usePublicRuntimeConfigScope('checkout');
-});

package/examples/runtime-config-source.nuxt.config.ts

@@ -1,13 +0,0 @@
-import { defineNuxtConfig } from 'nuxt/config';
-import type {} from '@lorion-org/nuxt';
-
-export default defineNuxtConfig({
-  modules: ['@lorion-org/nuxt'],
-  lorion: {
-    runtimeConfig: {
-      source: {
-        paths: ['.runtimeconfig/runtime-config/*/runtime.config.json'],
-      },
-    },
-  },
-});

package/examples/selected-extensions.nuxt.config.ts

@@ -1,30 +0,0 @@
-import { defineNuxtConfig } from 'nuxt/config';
-import LorionNuxtModule, {
-  createNuxtExtensionBootstrap,
-  createNuxtExtensionLayerPaths,
-} from '@lorion-org/nuxt';
-
-const extensionBootstrap = createNuxtExtensionBootstrap({
-  rootDir: __dirname,
-  options: {
-    defaultSelection: 'default',
-    descriptorPaths: ['extensions/*/extension.json'],
-  },
-});
-
-export default defineNuxtConfig({
-  extends: createNuxtExtensionLayerPaths(extensionBootstrap),
-  modules: [
-    [
-      LorionNuxtModule,
-      {
-        extensionBootstrap,
-        providers: {
-          configuredProviders: {
-            'payment-checkout': 'payment-provider-stripe',
-          },
-        },
-      },
-    ],
-  ],
-});