@rmc-toolkit/core 0.1.0 → 0.2.3

package/README.md

@@ -0,0 +1,64 @@
+# @rmc-toolkit/core
+
+Framework-agnostic core of [Runtime Module Composition](https://runtime-module-composition.dev): manifest-driven import map generation, route resolution, dynamic module loading, and a runtime host lifecycle that the Vite/React/Vue adapters build on. Has no dependency on any bundler or UI framework.
+
+## Install
+
+```bash
+npm install @rmc-toolkit/core
+```
+
+## Quick example
+
+```ts
+// runtime-composition.manifest.ts
+import { defineManifest } from "@rmc-toolkit/core";
+
+export const manifest = defineManifest({
+  namespace: "@acme",
+  assetsOrigin: "https://assets.example.com",
+  externalDepsOrigin: "https://esm.sh",
+  externalDeps: [
+    // The shared React singleton every other entry's peerDeps pins to by
+    // name. Has no peer deps of its own, so it opts out of defaultPeerDeps
+    // rather than self-referencing itself.
+    { name: "react", version: "19.2.7", peerDeps: false },
+    // Needs the same React instance — matches defaultPeerDeps below, so no
+    // peerDeps field needed here.
+    { name: "react-dom/client", version: "19.2.7" },
+    {
+      name: "@radix-ui/themes",
+      version: "3.3.0",
+      // Needs both react and react-dom, which differs from defaultPeerDeps
+      // — their versions are looked up from the entries above at
+      // generation time, never hand-typed here.
+      peerDeps: ["react", "react-dom"],
+    },
+  ],
+  // Applied automatically to every externalDeps entry that doesn't set its
+  // own peerDeps (react-dom/client, above).
+  defaultPeerDeps: ["react"],
+});
+```
+
+`createRuntimeHost` resolves a path to a slice's module specifier via the manifest, imports it, and mounts/unmounts it — with built-in error recovery and protection against rapid-navigation races. It only reacts to a path string; wire it to whatever produces navigation events (a `popstate` listener, as above, or a router's own navigation callback).
+
+If you're building a React or Vue host, use [`@rmc-toolkit/react`](https://www.npmjs.com/package/@rmc-toolkit/react) or [`@rmc-toolkit/vue`](https://www.npmjs.com/package/@rmc-toolkit/vue) instead — both wrap this same lifecycle in a framework-idiomatic hook/composable. Use this package directly for a host with no framework, or one without a dedicated adapter yet.
+
+## What's in here
+
+- `defineManifest`, `validateManifest` — declare and lint the manifest that drives everything else.
+- `createImportMap`, `createImportMapBootstrapScript`, `resolveImportMapSpecifier` — generate the browser import map from a manifest.
+- `resolveRoute` — resolve a URL path to a slice's module specifier.
+- `createExternalMatcher`, `listExternalSpecifiers` — determine which specifiers a bundler should leave external (used by `@rmc-toolkit/vite`).
+- `importModule`, `unwrapDefault` — the dynamic-import primitive slices/hosts load through.
+- `createRuntimeHost`, `createRuntimeHostObservable`, `notifyInternalNavigation` — the resolve/import/mount/unmount lifecycle, plain and as a subscribable observable.
+
+Full signatures and behavior for every export: [API Reference](https://runtime-module-composition.dev/api-reference/#core-rmc-toolkitcore).
+
+## Documentation
+
+- [Getting Started](https://runtime-module-composition.dev/getting-started/) — install and wire up a host + slice end to end
+- [API Reference](https://runtime-module-composition.dev/api-reference/#core-rmc-toolkitcore)
+- [Technical Implementation](https://runtime-module-composition.dev/technical-implementation/) — the architecture and failure modes behind the pattern
+- [Multi-Framework Demo](https://runtime-module-composition.dev/demo/) — a full, runnable reference implementation

package/dist/externals.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"externals.d.ts","sourceRoot":"","sources":["../src/externals.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,0BAA0B,EAE3B,MAAM,YAAY,CAAC;AAKpB,eAAO,MAAM,sBAAsB,GACjC,UAAU,0BAA0B,KACnC,MAAM,EAiBR,CAAC;AAEF,eAAO,MAAM,qBAAqB,GAChC,UAAU,0BAA0B,KACnC,CAAC,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAW9B,CAAC"}
+{"version":3,"file":"externals.d.ts","sourceRoot":"","sources":["../src/externals.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,0BAA0B,EAE3B,MAAM,YAAY,CAAC;AAMpB,eAAO,MAAM,sBAAsB,GACjC,UAAU,0BAA0B,KACnC,MAAM,EAiBR,CAAC;AAEF,eAAO,MAAM,qBAAqB,GAChC,UAAU,0BAA0B,KACnC,CAAC,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAW9B,CAAC"}

package/dist/externals.js

@@ -1,7 +1,8 @@
+import { trimTrailingSlash } from "./manifest.js";
 const isSharedExternal = (config) => typeof config === "string" ? true : config.external !== false;
 export const listExternalSpecifiers = (manifest) => {
     const prefixes = [
-        `${manifest.namespace}/`,
+        `${trimTrailingSlash(manifest.namespace)}/`,
         manifest.externalDepsOrigin
             ? (manifest.externalDepsPrefix ?? "@esm.sh/")
             : null,
@@ -16,7 +17,7 @@ export const listExternalSpecifiers = (manifest) => {
 };
 export const createExternalMatcher = (manifest) => {
     const exactSpecifiers = new Set(listExternalSpecifiers(manifest));
-    const namespacePrefix = `${manifest.namespace}/`;
+    const namespacePrefix = `${trimTrailingSlash(manifest.namespace)}/`;
     const externalDepsPrefix = manifest.externalDepsOrigin
         ? (manifest.externalDepsPrefix ?? "@esm.sh/")
         : null;

package/dist/host-observable.d.ts

@@ -0,0 +1,23 @@
+import type { RuntimeHostOptions } from "./host.js";
+export type RuntimeHostStatus = {
+    type: "idle";
+} | {
+    type: "loading";
+    path: string;
+} | {
+    type: "ready";
+    path: string;
+} | {
+    type: "error";
+    path: string;
+    error: unknown;
+};
+export type RuntimeHostObservableOptions = Pick<RuntimeHostOptions, "manifest" | "target" | "importer">;
+export type RuntimeHostObservable = {
+    next(path: string): void;
+    subscribe(observer: (status: RuntimeHostStatus) => void): () => void;
+    getSnapshot(): RuntimeHostStatus;
+    destroy(): Promise<void>;
+};
+export declare const createRuntimeHostObservable: (options: RuntimeHostObservableOptions) => RuntimeHostObservable;
+//# sourceMappingURL=host-observable.d.ts.map

package/dist/host-observable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-observable.d.ts","sourceRoot":"","sources":["../src/host-observable.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAEpD,MAAM,MAAM,iBAAiB,GACzB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC/B;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC;AAEpD,MAAM,MAAM,4BAA4B,GAAG,IAAI,CAC7C,kBAAkB,EAClB,UAAU,GAAG,QAAQ,GAAG,UAAU,CACnC,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,SAAS,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,iBAAiB,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IACrE,WAAW,IAAI,iBAAiB,CAAC;IACjC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B,CAAC;AAEF,eAAO,MAAM,2BAA2B,GACtC,SAAS,4BAA4B,KACpC,qBAsCF,CAAC"}

package/dist/host-observable.js

@@ -0,0 +1,37 @@
+import { createRuntimeHost } from "./host.js";
+export const createRuntimeHostObservable = (options) => {
+    let currentStatus = { type: "idle" };
+    const observers = new Set();
+    const setStatus = (status) => {
+        currentStatus = status;
+        for (const observer of observers) {
+            observer(status);
+        }
+    };
+    const host = createRuntimeHost({
+        ...options,
+        onLoading: (path) => setStatus({ type: "loading", path }),
+        onReady: (path) => setStatus({ type: "ready", path }),
+        onError: (error, path) => setStatus({ type: "error", path, error }),
+    });
+    return {
+        next(path) {
+            // Fire-and-forget is safe here: resolveAndMount() never throws or
+            // rejects — it catches everything internally and reports failures via
+            // onError, which setStatus() above turns into an "error" status.
+            void host.resolveAndMount(path);
+        },
+        subscribe(observer) {
+            observers.add(observer);
+            return () => {
+                observers.delete(observer);
+            };
+        },
+        getSnapshot() {
+            return currentStatus;
+        },
+        destroy() {
+            return host.destroy();
+        },
+    };
+};

package/dist/host-observable.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=host-observable.test.d.ts.map

package/dist/host-observable.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-observable.test.d.ts","sourceRoot":"","sources":["../src/host-observable.test.ts"],"names":[],"mappings":""}

package/dist/host-observable.test.js

@@ -0,0 +1,177 @@
+// @vitest-environment happy-dom
+import { describe, expect, test, vi } from "vitest";
+import { defineManifest } from "./manifest.js";
+import { createRuntimeHostObservable, } from "./host-observable.js";
+const manifest = defineManifest({
+    namespace: "@acme",
+    assetsOrigin: "https://assets.example.com",
+    sliceOverrides: {
+        search: { route: "/search/*", specifier: "@acme/search/index.mjs", entry: "index.mjs" },
+        cart: { route: "/cart/*", specifier: "@acme/cart/index.mjs", entry: "index.mjs" },
+    },
+});
+const createMockModule = () => ({
+    mount: vi.fn(async () => { }),
+    unmount: vi.fn(async () => { }),
+});
+describe("createRuntimeHostObservable", () => {
+    test("starts with an idle status", () => {
+        const target = document.createElement("div");
+        const observable = createRuntimeHostObservable({ manifest, target });
+        expect(observable.getSnapshot()).toEqual({ type: "idle" });
+    });
+    test("transitions loading -> ready on a successful next() call", async () => {
+        const searchModule = createMockModule();
+        const importer = vi.fn(async () => ({ default: searchModule }));
+        const target = document.createElement("div");
+        const statuses = [];
+        const observable = createRuntimeHostObservable({ manifest, target, importer });
+        observable.subscribe((status) => statuses.push(status));
+        observable.next("/search");
+        await vi.waitFor(() => {
+            expect(observable.getSnapshot()).toEqual({ type: "ready", path: "/search" });
+        });
+        expect(statuses).toEqual([
+            { type: "loading", path: "/search" },
+            { type: "ready", path: "/search" },
+        ]);
+        expect(searchModule.mount).toHaveBeenCalledTimes(1);
+    });
+    test("transitions to error when no route matches", async () => {
+        const target = document.createElement("div");
+        const importer = vi.fn();
+        const observable = createRuntimeHostObservable({ manifest, target, importer });
+        observable.next("/");
+        await vi.waitFor(() => {
+            expect(observable.getSnapshot().type).toBe("error");
+        });
+        const status = observable.getSnapshot();
+        if (status.type !== "error")
+            throw new Error("expected error status");
+        expect(status.path).toBe("/");
+        expect(status.error).toBeInstanceOf(Error);
+    });
+    test("transitions to error when the importer rejects", async () => {
+        const target = document.createElement("div");
+        const importer = vi.fn(async () => {
+            throw new Error("network failure");
+        });
+        const observable = createRuntimeHostObservable({ manifest, target, importer });
+        observable.next("/search");
+        await vi.waitFor(() => {
+            expect(observable.getSnapshot().type).toBe("error");
+        });
+    });
+    test("notifies multiple independent subscribers identically", async () => {
+        const searchModule = createMockModule();
+        const importer = vi.fn(async () => ({ default: searchModule }));
+        const target = document.createElement("div");
+        const first = [];
+        const second = [];
+        const observable = createRuntimeHostObservable({ manifest, target, importer });
+        observable.subscribe((status) => first.push(status));
+        observable.subscribe((status) => second.push(status));
+        observable.next("/search");
+        await vi.waitFor(() => {
+            expect(observable.getSnapshot()).toEqual({ type: "ready", path: "/search" });
+        });
+        expect(first).toEqual(second);
+    });
+    test("unsubscribe stops further notifications", async () => {
+        const searchModule = createMockModule();
+        const cartModule = createMockModule();
+        const importer = vi.fn(async (specifier) => ({
+            default: specifier === "@acme/search/index.mjs" ? searchModule : cartModule,
+        }));
+        const target = document.createElement("div");
+        const statuses = [];
+        const observable = createRuntimeHostObservable({ manifest, target, importer });
+        const unsubscribe = observable.subscribe((status) => statuses.push(status));
+        observable.next("/search");
+        await vi.waitFor(() => {
+            expect(observable.getSnapshot()).toEqual({ type: "ready", path: "/search" });
+        });
+        unsubscribe();
+        statuses.length = 0;
+        observable.next("/cart");
+        await vi.waitFor(() => {
+            expect(observable.getSnapshot()).toEqual({ type: "ready", path: "/cart" });
+        });
+        expect(statuses).toEqual([]);
+    });
+    test("getSnapshot returns the same object reference until the next transition", async () => {
+        const searchModule = createMockModule();
+        const importer = vi.fn(async () => ({ default: searchModule }));
+        const target = document.createElement("div");
+        const observable = createRuntimeHostObservable({ manifest, target, importer });
+        observable.next("/search");
+        await vi.waitFor(() => {
+            expect(observable.getSnapshot()).toEqual({ type: "ready", path: "/search" });
+        });
+        const first = observable.getSnapshot();
+        const second = observable.getSnapshot();
+        expect(first).toBe(second);
+    });
+    test("navigating to the same specifier again does not change status", async () => {
+        const searchModule = createMockModule();
+        const importer = vi.fn(async () => ({ default: searchModule }));
+        const target = document.createElement("div");
+        const statuses = [];
+        const observable = createRuntimeHostObservable({ manifest, target, importer });
+        observable.next("/search");
+        await vi.waitFor(() => {
+            expect(observable.getSnapshot()).toEqual({ type: "ready", path: "/search" });
+        });
+        observable.subscribe((status) => statuses.push(status));
+        observable.next("/search/results");
+        expect(statuses).toEqual([]);
+    });
+    test("destroy() unmounts the current module", async () => {
+        const searchModule = createMockModule();
+        const importer = vi.fn(async () => ({ default: searchModule }));
+        const target = document.createElement("div");
+        const observable = createRuntimeHostObservable({ manifest, target, importer });
+        observable.next("/search");
+        await vi.waitFor(() => {
+            expect(observable.getSnapshot()).toEqual({ type: "ready", path: "/search" });
+        });
+        await observable.destroy();
+        expect(searchModule.unmount).toHaveBeenCalledTimes(1);
+    });
+    test("does not broadcast status from a stale call that loses the race", async () => {
+        const searchModule = createMockModule();
+        const cartModule = createMockModule();
+        const target = document.createElement("div");
+        const statuses = [];
+        let resolveSearchImport;
+        const searchImportPromise = new Promise((resolve) => {
+            resolveSearchImport = resolve;
+        });
+        const importer = vi.fn(async (specifier) => {
+            if (specifier === "@acme/search/index.mjs") {
+                return searchImportPromise;
+            }
+            return { default: cartModule };
+        });
+        const observable = createRuntimeHostObservable({ manifest, target, importer });
+        observable.subscribe((status) => statuses.push(status));
+        observable.next("/search");
+        observable.next("/cart");
+        await vi.waitFor(() => {
+            expect(observable.getSnapshot()).toEqual({ type: "ready", path: "/cart" });
+        });
+        resolveSearchImport({ default: searchModule });
+        // Give the resumed stale call a chance to (incorrectly) broadcast, if it were going to.
+        await new Promise((resolve) => setTimeout(resolve, 0));
+        expect(observable.getSnapshot()).toEqual({ type: "ready", path: "/cart" });
+        // "/search" legitimately gets its own "loading" status (it was still the
+        // latest call at that synchronous instant, before "/cart" pre-empted it),
+        // but it must never reach "ready" or "error" once it has lost the race —
+        // only "/cart"'s own loading -> ready pair should follow.
+        expect(statuses).toEqual([
+            { type: "loading", path: "/search" },
+            { type: "loading", path: "/cart" },
+            { type: "ready", path: "/cart" },
+        ]);
+    });
+});

package/dist/host.d.ts

@@ -3,6 +3,7 @@ export type RuntimeHostOptions = {
     manifest: RuntimeCompositionManifest;
     target: Element;
     onLoading?: (path: string) => void;
+    onReady?: (path: string) => void;
     onError?: (error: unknown, path: string) => void;
     importer?: DynamicImporter;
 };

package/dist/host.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../src/host.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,eAAe,EACf,0BAA0B,EAE3B,MAAM,YAAY,CAAC;AAEpB,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,EAAE,0BAA0B,CAAC;IACrC,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACnC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACjD,QAAQ,CAAC,EAAE,eAAe,CAAC;CAC5B,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B,CAAC;AAEF,eAAO,MAAM,iBAAiB,GAAI,SAAS,kBAAkB,KAAG,WA2G/D,CAAC;AAEF,eAAO,MAAM,wBAAwB,GAAI,MAAM,MAAM,KAAG,IAGvD,CAAC"}
+{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../src/host.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,eAAe,EACf,0BAA0B,EAE3B,MAAM,YAAY,CAAC;AAEpB,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,EAAE,0BAA0B,CAAC;IACrC,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACnC,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACjC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACjD,QAAQ,CAAC,EAAE,eAAe,CAAC;CAC5B,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B,CAAC;AAEF,eAAO,MAAM,iBAAiB,GAAI,SAAS,kBAAkB,KAAG,WAgH/D,CAAC;AAEF,eAAO,MAAM,wBAAwB,GAAI,MAAM,MAAM,KAAG,IAGvD,CAAC"}

package/dist/host.js

@@ -3,6 +3,7 @@ import { resolveRoute } from "./routes.js";
 export const createRuntimeHost = (options) => {
     const { manifest, target, importer } = options;
     const onLoading = options.onLoading ?? (() => { });
+    const onReady = options.onReady ?? (() => { });
     // Reuse one generic message for both "no route matched" and "import/mount
     // failed" — the default UI's job is "something's wrong", not a diagnostic
     // surface; pass a custom onError to differentiate them.
@@ -72,6 +73,9 @@ export const createRuntimeHost = (options) => {
             // (the earlier, easily-hit case of an older call clobbering a newer
             // call's already-*settled* mount).
             await runtimeModule.mount(target, { route: match, manifest });
+            if (token === latestToken) {
+                onReady(path);
+            }
         }
         catch (error) {
             if (token === latestToken) {

package/dist/host.test.js

@@ -125,6 +125,68 @@ describe("createRuntimeHost", () => {
         expect(onLoading).toHaveBeenCalledTimes(1);
         expect(onLoading).toHaveBeenCalledWith("/search");
     });
+    test("calls onReady with the path after a successful mount", async () => {
+        const onReady = vi.fn();
+        const searchModule = createMockModule();
+        const importer = vi.fn(async () => ({ default: searchModule }));
+        const target = document.createElement("div");
+        const host = createRuntimeHost({ manifest, target, importer, onReady });
+        await host.resolveAndMount("/search");
+        expect(onReady).toHaveBeenCalledTimes(1);
+        expect(onReady).toHaveBeenCalledWith("/search");
+    });
+    test("does not call onReady for a stale call that loses the race", async () => {
+        const onReady = vi.fn();
+        const searchModule = createMockModule();
+        const cartModule = createMockModule();
+        const target = document.createElement("div");
+        let resolveSearchImport;
+        const searchImportPromise = new Promise((resolve) => {
+            resolveSearchImport = resolve;
+        });
+        const importer = vi.fn(async (specifier) => {
+            if (specifier === "@acme/search/index.mjs") {
+                return searchImportPromise;
+            }
+            return { default: cartModule };
+        });
+        const host = createRuntimeHost({ manifest, target, importer, onReady });
+        const firstCall = host.resolveAndMount("/search");
+        const secondCall = host.resolveAndMount("/cart");
+        await secondCall;
+        resolveSearchImport({ default: searchModule });
+        await firstCall;
+        expect(onReady).toHaveBeenCalledTimes(1);
+        expect(onReady).toHaveBeenCalledWith("/cart");
+    });
+    test("does not call onReady for a call whose mount() finishes after a newer call has already taken over", async () => {
+        const onReady = vi.fn();
+        const target = document.createElement("div");
+        let resolveSearchMount;
+        const searchMountPromise = new Promise((resolve) => {
+            resolveSearchMount = resolve;
+        });
+        const searchModule = {
+            mount: vi.fn(() => searchMountPromise),
+            unmount: vi.fn(async () => { }),
+        };
+        const cartModule = createMockModule();
+        const importer = vi.fn(async (specifier) => ({
+            default: specifier === "@acme/search/index.mjs" ? searchModule : cartModule,
+        }));
+        const host = createRuntimeHost({ manifest, target, importer, onReady });
+        const firstCall = host.resolveAndMount("/search");
+        // Let the first call's import resolve and its mount() begin (and hang).
+        await vi.waitFor(() => {
+            expect(searchModule.mount).toHaveBeenCalled();
+        });
+        const secondCall = host.resolveAndMount("/cart");
+        await secondCall;
+        resolveSearchMount();
+        await firstCall;
+        expect(onReady).toHaveBeenCalledTimes(1);
+        expect(onReady).toHaveBeenCalledWith("/cart");
+    });
     test("calls onError (not the 'no slice matches' message) when unmounting during a no-match navigation itself throws", async () => {
         const onError = vi.fn();
         const target = document.createElement("div");

package/dist/import-map.d.ts

@@ -5,4 +5,12 @@ export type CreateImportMapOptions = {
 };
 export declare const createImportMap: (manifest: RuntimeCompositionManifest, options?: CreateImportMapOptions) => ImportMap;
 export declare const createImportMapBootstrapScript: (manifest: RuntimeCompositionManifest, options?: CreateImportMapOptions) => string;
+/**
+ * Resolves a specifier against an already-generated ImportMap the same way
+ * a browser resolves import maps: an exact key wins; otherwise the longest
+ * key ending in "/" that the specifier starts with (a prefix mapping),
+ * with the remainder appended to that prefix's target. Returns undefined
+ * if nothing matches.
+ */
+export declare const resolveImportMapSpecifier: (importMap: ImportMap, specifier: string) => string | undefined;
 //# sourceMappingURL=import-map.d.ts.map

package/dist/import-map.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"import-map.d.ts","sourceRoot":"","sources":["../src/import-map.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,SAAS,EACT,0BAA0B,EAC1B,kBAAkB,EAGnB,MAAM,YAAY,CAAC;AA4BpB,MAAM,MAAM,sBAAsB,GAAG;IACnC,WAAW,CAAC,EAAE,kBAAkB,CAAC;IACjC,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AA6BF,eAAO,MAAM,eAAe,GAC1B,UAAU,0BAA0B,EACpC,UAAS,sBAA2B,KACnC,SAiDF,CAAC;AAIF,eAAO,MAAM,8BAA8B,GACzC,UAAU,0BAA0B,EACpC,UAAS,sBAA2B,KACnC,MAwCF,CAAC"}
+{"version":3,"file":"import-map.d.ts","sourceRoot":"","sources":["../src/import-map.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,SAAS,EACT,0BAA0B,EAC1B,kBAAkB,EAGnB,MAAM,YAAY,CAAC;AA4BpB,MAAM,MAAM,sBAAsB,GAAG;IACnC,WAAW,CAAC,EAAE,kBAAkB,CAAC;IACjC,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AAsFF,eAAO,MAAM,eAAe,GAC1B,UAAU,0BAA0B,EACpC,UAAS,sBAA2B,KACnC,SAgDF,CAAC;AAIF,eAAO,MAAM,8BAA8B,GACzC,UAAU,0BAA0B,EACpC,UAAS,sBAA2B,KACnC,MAwCF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,GACpC,WAAW,SAAS,EACpB,WAAW,MAAM,KAChB,MAAM,GAAG,SA4BX,CAAC"}

package/dist/import-map.js

@@ -1,4 +1,4 @@
-import { joinUrl } from "./manifest.js";
+import { joinUrl, splitPackageSpecifier } from "./manifest.js";
 const resolveSharedDependencyUrl = (config, environment) => {
     if (typeof config === "string") {
         return config;
@@ -13,9 +13,6 @@ const resolveSliceUrl = (manifest, slice, environment) => {
     return joinUrl(manifest.assetsOrigin, entry);
 };
 const ensurePrefix = (value) => value.endsWith("/") ? value : `${value}/`;
-const buildDepsQuery = (peerDeps) => Object.entries(peerDeps)
-    .map(([name, version]) => `${name}@${version}`)
-    .join(",");
 const applyDevFlag = (value, externalDepsOrigin) => {
     if (!value.startsWith(externalDepsOrigin)) {
         return value;
@@ -25,6 +22,51 @@ const applyDevFlag = (value, externalDepsOrigin) => {
 const resolveAssetsOrigin = (manifest, environment) => manifest.environments?.[environment]?.assetsOrigin ?? manifest.assetsOrigin;
 const resolveExternalDepsOrigin = (manifest, environment) => manifest.environments?.[environment]?.externalDepsOrigin ??
     manifest.externalDepsOrigin;
+/**
+ * One basePackage -> version lookup built from every externalDeps entry.
+ * If two entries share a basePackage but declare different versions, the
+ * FIRST-declared one wins here (used only for resolving other entries'
+ * peerDeps references) — each entry's own URL is still built from its own
+ * declared version regardless of what wins this lookup, so a genuine
+ * conflict stays visible in the generated map rather than being silently
+ * normalized away. See validateManifest for the diagnostic that surfaces
+ * this class of mistake.
+ */
+const buildVersionIndex = (entries) => {
+    const index = new Map();
+    for (const entry of entries) {
+        const { basePackage } = splitPackageSpecifier(entry.name);
+        if (!index.has(basePackage)) {
+            index.set(basePackage, { version: entry.version, entryName: entry.name });
+        }
+    }
+    return index;
+};
+/** Inserts `@version` right after the base package, preserving any subpath:
+ *  "react-dom/client" + "19.2.4" -> ".../react-dom@19.2.4/client". */
+const buildVersionedUrl = (origin, name, version) => {
+    const { basePackage, subpath } = splitPackageSpecifier(name);
+    const versionedPath = subpath
+        ? `${basePackage}@${version}/${subpath}`
+        : `${basePackage}@${version}`;
+    return joinUrl(origin, versionedPath);
+};
+const resolvePeerNames = (entry, defaultPeerDeps) => {
+    if (entry.peerDeps === false) {
+        return [];
+    }
+    return entry.peerDeps ?? defaultPeerDeps ?? [];
+};
+/** A peer name with no matching externalDeps entry is silently omitted —
+ *  createImportMap never throws; validateManifest is where that mistake
+ *  gets surfaced, at warning level. */
+const buildDepsQuery = (peerNames, versionIndex) => peerNames
+    .map((peerName) => {
+    const resolved = versionIndex.get(peerName);
+    return resolved ? `${peerName}@${resolved.version}` : null;
+})
+    .filter((value) => value !== null)
+    .join(",");
 export const createImportMap = (manifest, options = {}) => {
     const environment = options.environment ?? "production";
     const imports = {};
@@ -34,14 +76,14 @@ export const createImportMap = (manifest, options = {}) => {
     const externalDepsPrefix = ensurePrefix(manifest.externalDepsPrefix ?? "@esm.sh/");
     if (externalDepsOrigin) {
         imports[externalDepsPrefix] = ensurePrefix(externalDepsOrigin);
-        for (const entry of manifest.externalDeps ?? []) {
-            const name = typeof entry === "string" ? entry : entry.name;
-            const peerDeps = typeof entry === "string" ? manifest.defaultPeerDeps : entry.peerDeps;
-            const specifier = `${externalDepsPrefix}${name}`;
-            const baseUrl = joinUrl(externalDepsOrigin, name);
-            imports[specifier] = peerDeps
-                ? `${baseUrl}?deps=${buildDepsQuery(peerDeps)}`
-                : baseUrl;
+        const externalDeps = manifest.externalDeps ?? [];
+        const versionIndex = buildVersionIndex(externalDeps);
+        for (const entry of externalDeps) {
+            const specifier = `${externalDepsPrefix}${entry.name}`;
+            const baseUrl = buildVersionedUrl(externalDepsOrigin, entry.name, entry.version);
+            const peerNames = resolvePeerNames(entry, manifest.defaultPeerDeps);
+            const depsQuery = buildDepsQuery(peerNames, versionIndex);
+            imports[specifier] = depsQuery ? `${baseUrl}?deps=${depsQuery}` : baseUrl;
         }
     }
     for (const [specifier, config] of Object.entries(manifest.exactImports ?? {})) {
@@ -104,3 +146,34 @@ export const createImportMapBootstrapScript = (manifest, options = {}) => {
 })();
 `;
 };
+/**
+ * Resolves a specifier against an already-generated ImportMap the same way
+ * a browser resolves import maps: an exact key wins; otherwise the longest
+ * key ending in "/" that the specifier starts with (a prefix mapping),
+ * with the remainder appended to that prefix's target. Returns undefined
+ * if nothing matches.
+ */
+export const resolveImportMapSpecifier = (importMap, specifier) => {
+    if (specifier in importMap.imports) {
+        return importMap.imports[specifier];
+    }
+    let bestPrefix;
+    for (const key of Object.keys(importMap.imports)) {
+        if (key.endsWith("/") &&
+            specifier.startsWith(key) &&
+            (bestPrefix === undefined || key.length > bestPrefix.length)) {
+            bestPrefix = key;
+        }
+    }
+    if (bestPrefix === undefined) {
+        return undefined;
+    }
+    // bestPrefix is always a real key of importMap.imports (it's derived from
+    // Object.keys(importMap.imports) above), so this lookup can't actually be
+    // undefined — but note this is a hand-proven invariant, not something the
+    // type checker enforces here: TypeScript's `+` operator doesn't propagate
+    // noUncheckedIndexedAccess's `| undefined` the way a direct type
+    // annotation would. If bestPrefix's derivation ever changes, re-verify
+    // this invariant still holds.
+    return importMap.imports[bestPrefix] + specifier.slice(bestPrefix.length);
+};

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./externals.js";
+export * from "./host-observable.js";
 export * from "./host.js";
 export * from "./import-map.js";
 export * from "./loader.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,sBAAsB,CAAC;AACrC,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC"}

package/dist/index.js

@@ -1,4 +1,5 @@
 export * from "./externals.js";
+export * from "./host-observable.js";
 export * from "./host.js";
 export * from "./import-map.js";
 export * from "./loader.js";

package/dist/index.test.js

@@ -1,12 +1,36 @@
 // @vitest-environment happy-dom
 import { describe, expect, test, vi } from "vitest";
-import { createExternalMatcher, createImportMap, createImportMapBootstrapScript, createRuntimeHost, defineManifest, notifyInternalNavigation, resolveRoute, validateManifest, } from "./index.js";
+import { createExternalMatcher, createImportMap, createImportMapBootstrapScript, createRuntimeHost, createRuntimeHostObservable, defineManifest, notifyInternalNavigation, resolveImportMapSpecifier, resolveRoute, splitPackageSpecifier, validateManifest, } from "./index.js";
 const manifest = defineManifest({
     namespace: "@acme",
     assetsOrigin: "https://assets.example.com",
     externalDepsOrigin: "https://esm.sh",
 });
 describe("runtime composition core", () => {
+    test("splitPackageSpecifier splits a bare package name with no subpath", () => {
+        expect(splitPackageSpecifier("react")).toEqual({
+            basePackage: "react",
+            subpath: null,
+        });
+    });
+    test("splitPackageSpecifier splits a package name with a subpath", () => {
+        expect(splitPackageSpecifier("react-dom/client")).toEqual({
+            basePackage: "react-dom",
+            subpath: "client",
+        });
+    });
+    test("splitPackageSpecifier splits a scoped package name with no subpath", () => {
+        expect(splitPackageSpecifier("@radix-ui/themes")).toEqual({
+            basePackage: "@radix-ui/themes",
+            subpath: null,
+        });
+    });
+    test("splitPackageSpecifier splits a scoped package name with a multi-segment subpath", () => {
+        expect(splitPackageSpecifier("@radix-ui/themes/some/path")).toEqual({
+            basePackage: "@radix-ui/themes",
+            subpath: "some/path",
+        });
+    });
     test("creates an import map from namespace and external dependency origins", () => {
         expect(createImportMap(manifest)).toEqual({
             imports: {
@@ -49,29 +73,37 @@ describe("runtime composition core", () => {
             },
         });
     });
-    test("generates externalDeps entries with defaultPeerDeps applied to bare strings", () => {
+    test("generates externalDeps entries with defaultPeerDeps resolved from a sibling entry's version", () => {
         expect(createImportMap({
             ...manifest,
-            externalDeps: ["zustand"],
-            defaultPeerDeps: { react: "19.2.4" },
+            externalDeps: [
+                { name: "react", version: "19.2.4", peerDeps: false },
+                { name: "zustand", version: "4.5.0" },
+            ],
+            defaultPeerDeps: ["react"],
         })).toEqual({
             imports: {
                 "@acme/": "https://assets.example.com/",
                 "@esm.sh/": "https://esm.sh/",
-                "@esm.sh/zustand": "https://esm.sh/zustand?deps=react@19.2.4",
+                "@esm.sh/react": "https://esm.sh/react@19.2.4",
+                "@esm.sh/zustand": "https://esm.sh/zustand@4.5.0?deps=react@19.2.4",
             },
         });
     });
     test("supports externalDeps entries that opt out of peerDeps", () => {
         expect(createImportMap({
             ...manifest,
-            externalDeps: [{ name: "date-fns", peerDeps: false }],
-            defaultPeerDeps: { react: "19.2.4" },
+            externalDeps: [
+                { name: "react", version: "19.2.4", peerDeps: false },
+                { name: "date-fns", version: "3.6.0", peerDeps: false },
+            ],
+            defaultPeerDeps: ["react"],
         })).toEqual({
             imports: {
                 "@acme/": "https://assets.example.com/",
                 "@esm.sh/": "https://esm.sh/",
-                "@esm.sh/date-fns": "https://esm.sh/date-fns",
+                "@esm.sh/react": "https://esm.sh/react@19.2.4",
+                "@esm.sh/date-fns": "https://esm.sh/date-fns@3.6.0",
             },
         });
     });
@@ -79,45 +111,155 @@ describe("runtime composition core", () => {
         expect(createImportMap({
             ...manifest,
             externalDeps: [
+                { name: "react", version: "19.2.4", peerDeps: false },
+                { name: "react-dom", version: "19.2.4", peerDeps: false },
                 {
                     name: "@radix-ui/themes",
-                    peerDeps: { react: "19.2.4", "react-dom": "19.2.4/client" },
+                    version: "3.0.0",
+                    peerDeps: ["react", "react-dom"],
                 },
             ],
-            defaultPeerDeps: { react: "19.2.4" },
+            defaultPeerDeps: ["react"],
         })).toEqual({
             imports: {
                 "@acme/": "https://assets.example.com/",
                 "@esm.sh/": "https://esm.sh/",
-                "@esm.sh/@radix-ui/themes": "https://esm.sh/@radix-ui/themes?deps=react@19.2.4,react-dom@19.2.4/client",
+                "@esm.sh/react": "https://esm.sh/react@19.2.4",
+                "@esm.sh/react-dom": "https://esm.sh/react-dom@19.2.4",
+                "@esm.sh/@radix-ui/themes": "https://esm.sh/@radix-ui/themes@3.0.0?deps=react@19.2.4,react-dom@19.2.4",
             },
         });
     });
     test("devDeps appends ?dev to exact external entries but not the catch-all prefix", () => {
         expect(createImportMap({
             ...manifest,
-            externalDeps: ["zustand"],
-            defaultPeerDeps: { react: "19.2.4" },
+            externalDeps: [
+                { name: "react", version: "19.2.4", peerDeps: false },
+                { name: "zustand", version: "4.5.0" },
+            ],
+            defaultPeerDeps: ["react"],
         }, { devDeps: true })).toEqual({
             imports: {
                 "@acme/": "https://assets.example.com/",
                 "@esm.sh/": "https://esm.sh/",
-                "@esm.sh/zustand": "https://esm.sh/zustand?deps=react@19.2.4&dev",
+                "@esm.sh/react": "https://esm.sh/react@19.2.4?dev",
+                "@esm.sh/zustand": "https://esm.sh/zustand@4.5.0?deps=react@19.2.4&dev",
+            },
+        });
+    });
+    test("externalDeps entries resolve with no ?deps= query when defaultPeerDeps is unset", () => {
+        expect(createImportMap({
+            ...manifest,
+            externalDeps: [{ name: "zustand", version: "4.5.0" }],
+        })).toEqual({
+            imports: {
+                "@acme/": "https://assets.example.com/",
+                "@esm.sh/": "https://esm.sh/",
+                "@esm.sh/zustand": "https://esm.sh/zustand@4.5.0",
+            },
+        });
+    });
+    test("externalDeps entry's specifier key excludes the version while the URL includes it", () => {
+        expect(createImportMap({
+            ...manifest,
+            externalDeps: [{ name: "react", version: "19.2.4" }],
+        })).toEqual({
+            imports: {
+                "@acme/": "https://assets.example.com/",
+                "@esm.sh/": "https://esm.sh/",
+                "@esm.sh/react": "https://esm.sh/react@19.2.4",
+            },
+        });
+    });
+    test("a subpath externalDeps entry inserts the version after the base package, before the subpath", () => {
+        expect(createImportMap({
+            ...manifest,
+            externalDeps: [{ name: "react-dom/client", version: "19.2.4" }],
+        })).toEqual({
+            imports: {
+                "@acme/": "https://assets.example.com/",
+                "@esm.sh/": "https://esm.sh/",
+                "@esm.sh/react-dom/client": "https://esm.sh/react-dom@19.2.4/client",
+            },
+        });
+    });
+    test("an unresolvable peerDeps name is silently omitted rather than throwing", () => {
+        expect(createImportMap({
+            ...manifest,
+            externalDeps: [
+                { name: "react", version: "19.2.4", peerDeps: false },
+                {
+                    name: "@radix-ui/themes",
+                    version: "3.0.0",
+                    peerDeps: ["react", "svelte"],
+                },
+            ],
+        })).toEqual({
+            imports: {
+                "@acme/": "https://assets.example.com/",
+                "@esm.sh/": "https://esm.sh/",
+                "@esm.sh/react": "https://esm.sh/react@19.2.4",
+                // "svelte" has no externalDeps entry, so it's silently dropped from
+                // the query instead of throwing — only "react" resolves.
+                "@esm.sh/@radix-ui/themes": "https://esm.sh/@radix-ui/themes@3.0.0?deps=react@19.2.4",
             },
         });
     });
-    test("bare-string externalDeps entries resolve with no ?deps= query when defaultPeerDeps is unset", () => {
+    test("entries sharing a base package with different versions each keep their own URL, and peer lookups use the first-declared version", () => {
         expect(createImportMap({
             ...manifest,
-            externalDeps: ["zustand"],
+            externalDeps: [
+                { name: "react-dom", version: "19.2.4", peerDeps: false },
+                { name: "react-dom/client", version: "19.2.5", peerDeps: false },
+                { name: "react", version: "19.2.4", peerDeps: false },
+                {
+                    name: "@radix-ui/themes",
+                    version: "3.0.0",
+                    peerDeps: ["react-dom"],
+                },
+            ],
         })).toEqual({
             imports: {
                 "@acme/": "https://assets.example.com/",
                 "@esm.sh/": "https://esm.sh/",
-                "@esm.sh/zustand": "https://esm.sh/zustand",
+                // Each entry's own URL always uses its own declared version — the
+                // conflict (19.2.4 vs 19.2.5) stays visible here, it's never
+                // silently normalized to one value.
+                "@esm.sh/react-dom": "https://esm.sh/react-dom@19.2.4",
+                "@esm.sh/react-dom/client": "https://esm.sh/react-dom@19.2.5/client",
+                "@esm.sh/react": "https://esm.sh/react@19.2.4",
+                // Peer lookup for "react-dom" uses the FIRST-declared version
+                // (19.2.4, from the "react-dom" entry, not "react-dom/client").
+                "@esm.sh/@radix-ui/themes": "https://esm.sh/@radix-ui/themes@3.0.0?deps=react-dom@19.2.4",
             },
         });
     });
+    test("resolveImportMapSpecifier prefers an exact match over a shorter matching prefix", () => {
+        const importMap = createImportMap({
+            ...manifest,
+            externalDeps: [{ name: "react", version: "19.2.4" }],
+        });
+        expect(resolveImportMapSpecifier(importMap, "@esm.sh/react")).toBe("https://esm.sh/react@19.2.4");
+    });
+    test("resolveImportMapSpecifier resolves via the longest matching prefix when no exact key exists", () => {
+        const importMap = createImportMap(manifest);
+        expect(resolveImportMapSpecifier(importMap, "@acme/search/index.mjs")).toBe("https://assets.example.com/search/index.mjs");
+    });
+    test("resolveImportMapSpecifier prefers the longest of two overlapping prefix keys", () => {
+        const importMap = createImportMap({
+            ...manifest,
+            environments: {
+                development: {
+                    sliceOrigins: { search: "http://localhost:5174" },
+                },
+            },
+        }, { environment: "development" });
+        expect(resolveImportMapSpecifier(importMap, "@acme/search/index.mjs")).toBe("http://localhost:5174/index.mjs");
+    });
+    test("resolveImportMapSpecifier returns undefined when nothing matches", () => {
+        const importMap = createImportMap(manifest);
+        expect(resolveImportMapSpecifier(importMap, "lodash")).toBeUndefined();
+    });
     test("resolves routes by convention without explicit slice config", () => {
         expect(resolveRoute(manifest, "/search/routes")?.specifier).toBe("@acme/search/index.mjs");
     });
@@ -174,6 +316,61 @@ describe("runtime composition core", () => {
     test("validates the base manifest without errors", () => {
         expect(validateManifest(manifest).filter((item) => item.level === "error")).toHaveLength(0);
     });
+    test("validateManifest warns when externalDeps entries share a base package but declare different versions", () => {
+        const diagnostics = validateManifest({
+            ...manifest,
+            externalDeps: [
+                { name: "react-dom", version: "19.2.4" },
+                { name: "react-dom/client", version: "19.2.5" },
+            ],
+        });
+        expect(diagnostics.some((d) => d.level === "warning" && d.code === "external-deps-version-conflict")).toBe(true);
+    });
+    test("validateManifest emits exactly one warning for a group of 3+ conflicting entries, not one per pair", () => {
+        const diagnostics = validateManifest({
+            ...manifest,
+            externalDeps: [
+                { name: "react-dom", version: "19.2.4" },
+                { name: "react-dom/client", version: "19.2.5" },
+                { name: "react-dom/server", version: "19.2.6" },
+            ],
+        });
+        expect(diagnostics.filter((d) => d.code === "external-deps-version-conflict")).toHaveLength(1);
+    });
+    test("validateManifest does not warn when externalDeps entries sharing a base package agree on version", () => {
+        const diagnostics = validateManifest({
+            ...manifest,
+            externalDeps: [
+                { name: "react-dom", version: "19.2.4" },
+                { name: "react-dom/client", version: "19.2.4" },
+            ],
+        });
+        expect(diagnostics.some((d) => d.code === "external-deps-version-conflict")).toBe(false);
+    });
+    test("validateManifest warns when a peerDeps name has no matching externalDeps entry", () => {
+        const diagnostics = validateManifest({
+            ...manifest,
+            externalDeps: [
+                {
+                    name: "@radix-ui/themes",
+                    version: "3.0.0",
+                    peerDeps: ["react", "svelte"],
+                },
+            ],
+        });
+        expect(diagnostics.some((d) => d.level === "warning" && d.code === "external-deps-unresolvable-peer")).toBe(true);
+    });
+    test("validateManifest does not warn when every peerDeps name resolves, including via defaultPeerDeps", () => {
+        const diagnostics = validateManifest({
+            ...manifest,
+            externalDeps: [
+                { name: "react", version: "19.2.4", peerDeps: false },
+                { name: "@radix-ui/themes", version: "3.0.0" },
+            ],
+            defaultPeerDeps: ["react"],
+        });
+        expect(diagnostics.some((d) => d.code === "external-deps-unresolvable-peer")).toBe(false);
+    });
     test("createImportMapBootstrapScript generates valid, parseable JavaScript", () => {
         const script = createImportMapBootstrapScript(manifest);
         expect(() => new Function(script)).not.toThrow();
@@ -198,11 +395,14 @@ describe("runtime composition core", () => {
         expect(script).toContain('script.type = "importmap"');
     });
     test("createImportMapBootstrapScript's embedded dev-flag logic matches createImportMap's own devDeps behavior", () => {
-        const manifestWithExternalDeps = {
+        const manifestWithExternalDeps = defineManifest({
             ...manifest,
-            externalDeps: ["zustand"],
-            defaultPeerDeps: { react: "19.2.4" },
-        };
+            externalDeps: [
+                { name: "react", version: "19.2.4", peerDeps: false },
+                { name: "zustand", version: "4.5.0" },
+            ],
+            defaultPeerDeps: ["react"],
+        });
         const expectedWithDevDeps = createImportMap(manifestWithExternalDeps, {
             devDeps: true,
         }).imports;
@@ -237,4 +437,12 @@ describe("runtime composition core", () => {
         expect(mountSpy).toHaveBeenCalledTimes(1);
         expect(typeof notifyInternalNavigation).toBe("function");
     });
+    test("re-exports createRuntimeHostObservable from the public barrel", () => {
+        const target = document.createElement("div");
+        const observable = createRuntimeHostObservable({
+            manifest: { namespace: "@acme", assetsOrigin: "https://assets.example.com" },
+            target,
+        });
+        expect(observable.getSnapshot()).toEqual({ type: "idle" });
+    });
 });

package/dist/manifest.d.ts

@@ -1,6 +1,12 @@
-import type { RuntimeCompositionManifest } from "./types.js";
+import type { PackageSpecifier, RuntimeCompositionManifest } from "./types.js";
 export declare const defineManifest: <TManifest extends RuntimeCompositionManifest>(manifest: TManifest) => TManifest;
 export declare const trimTrailingSlash: (value: string) => string;
 export declare const trimLeadingSlash: (value: string) => string;
 export declare const joinUrl: (origin: string, path: string) => string;
+/**
+ * Splits a package specifier into its base package (handling scoped
+ * packages, e.g. "@radix-ui/themes") and an optional subpath (e.g.
+ * "react-dom/client" -> basePackage "react-dom", subpath "client").
+ */
+export declare const splitPackageSpecifier: (name: string) => PackageSpecifier;
 //# sourceMappingURL=manifest.d.ts.map

package/dist/manifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,YAAY,CAAC;AAE7D,eAAO,MAAM,cAAc,GAAI,SAAS,SAAS,0BAA0B,EACzE,UAAU,SAAS,KAClB,SAAqB,CAAC;AAEzB,eAAO,MAAM,iBAAiB,GAAI,OAAO,MAAM,KAAG,MACA,CAAC;AAEnD,eAAO,MAAM,gBAAgB,GAAI,OAAO,MAAM,KAAG,MACD,CAAC;AAEjD,eAAO,MAAM,OAAO,GAAI,QAAQ,MAAM,EAAE,MAAM,MAAM,KAAG,MACG,CAAC"}
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,0BAA0B,EAAE,MAAM,YAAY,CAAC;AAE/E,eAAO,MAAM,cAAc,GAAI,SAAS,SAAS,0BAA0B,EACzE,UAAU,SAAS,KAClB,SAAqB,CAAC;AAEzB,eAAO,MAAM,iBAAiB,GAAI,OAAO,MAAM,KAAG,MACA,CAAC;AAEnD,eAAO,MAAM,gBAAgB,GAAI,OAAO,MAAM,KAAG,MACD,CAAC;AAEjD,eAAO,MAAM,OAAO,GAAI,QAAQ,MAAM,EAAE,MAAM,MAAM,KAAG,MACG,CAAC;AAE3D;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,GAAI,MAAM,MAAM,KAAG,gBAmBpD,CAAC"}

package/dist/manifest.js

@@ -2,3 +2,26 @@ export const defineManifest = (manifest) => manifest;
 export const trimTrailingSlash = (value) => value.endsWith("/") ? value.slice(0, -1) : value;
 export const trimLeadingSlash = (value) => value.startsWith("/") ? value.slice(1) : value;
 export const joinUrl = (origin, path) => `${trimTrailingSlash(origin)}/${trimLeadingSlash(path)}`;
+/**
+ * Splits a package specifier into its base package (handling scoped
+ * packages, e.g. "@radix-ui/themes") and an optional subpath (e.g.
+ * "react-dom/client" -> basePackage "react-dom", subpath "client").
+ */
+export const splitPackageSpecifier = (name) => {
+    const segments = name.split("/");
+    if (name.startsWith("@")) {
+        const scope = segments[0] ?? "";
+        const packageName = segments[1] ?? "";
+        const rest = segments.slice(2);
+        return {
+            basePackage: `${scope}/${packageName}`,
+            subpath: rest.length > 0 ? rest.join("/") : null,
+        };
+    }
+    const packageName = segments[0] ?? name;
+    const rest = segments.slice(1);
+    return {
+        basePackage: packageName,
+        subpath: rest.length > 0 ? rest.join("/") : null,
+    };
+};

package/dist/types.d.ts

@@ -25,9 +25,21 @@ export type EnvironmentConfig = {
     externalDepsOrigin?: string;
     sliceOrigins?: Record<string, string>;
 };
-export type ExternalDepEntry = string | {
+export type PackageSpecifier = {
+    basePackage: string;
+    subpath: string | null;
+};
+export type ExternalDepEntry = {
+    /** Bare package name, or a subpath import, e.g. "react" or "react-dom/client". */
     name: string;
-    peerDeps?: Record<string, string> | false;
+    /** Always required — this is what prevents a bare entry from resolving to
+     *  an unpinned "latest" CDN build. */
+    version: string;
+    /** Peer package NAMES (not versions) to pin via esm.sh's `?deps=` query.
+     *  Versions are looked up from those names' own externalDeps entries at
+     *  generation time — never hand-typed here. `false` opts this entry out
+     *  of `defaultPeerDeps`. */
+    peerDeps?: string[] | false;
 };
 export type RuntimeCompositionManifest = {
     namespace: string;
@@ -40,7 +52,9 @@ export type RuntimeCompositionManifest = {
     sliceOverrides?: Record<string, SliceConfig>;
     routeOverrides?: Record<string, RouteOverrideConfig>;
     externalDeps?: ExternalDepEntry[];
-    defaultPeerDeps?: Record<string, string>;
+    /** Peer package NAMES applied automatically to every externalDeps entry
+     *  that doesn't set its own `peerDeps`. */
+    defaultPeerDeps?: string[];
 };
 export type RuntimeRouteMatch = {
     sliceName: string;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,SAAS,GAAG;IACtB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACjD,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG,aAAa,GAAG,SAAS,GAAG,YAAY,CAAC;AAE1E,MAAM,MAAM,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,kBAAkB,EAAE,MAAM,CAAC,CAAC,CAAC;AAE5E,MAAM,MAAM,sBAAsB,GAC9B,MAAM,GACN;IACE,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,iBAAiB,CAAC;IACjC,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEN,MAAM,MAAM,WAAW,GAAG;IACxB,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,iBAAiB,CAAC;IACjC,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAC3B,MAAM,GACN;IACE,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;CAC3B,CAAC;AAEN,MAAM,MAAM,iBAAiB,GAAG;IAC9B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACvC,CAAC;AAEF,MAAM,MAAM,gBAAgB,GACxB,MAAM,GACN;IACE,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,KAAK,CAAC;CAC3C,CAAC;AAEN,MAAM,MAAM,0BAA0B,GAAG;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,kBAAkB,EAAE,iBAAiB,CAAC,CAAC,CAAC;IACtE,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC;IACtD,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAC7C,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;IACrD,YAAY,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAClC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC1C,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC,CAAC;AAEF,MAAM,MAAM,4BAA4B,GAAG;IACzC,KAAK,EAAE,OAAO,GAAG,SAAS,CAAC;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,KAAK,CAAC,EAAE,iBAAiB,CAAC;IAC1B,QAAQ,CAAC,EAAE,0BAA0B,CAAC;IACtC,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,KAAK,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7E,OAAO,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAClC,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/validation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,4BAA4B,EAC5B,0BAA0B,EAC3B,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,gBAAgB,GAC3B,UAAU,0BAA0B,KACnC,4BAA4B,EAgF9B,CAAC"}
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,4BAA4B,EAC5B,0BAA0B,EAC3B,MAAM,YAAY,CAAC;AAGpB,eAAO,MAAM,gBAAgB,GAC3B,UAAU,0BAA0B,KACnC,4BAA4B,EAyH9B,CAAC"}

package/dist/validation.js

@@ -1,3 +1,4 @@
+import { splitPackageSpecifier } from "./manifest.js";
 export const validateManifest = (manifest) => {
     const diagnostics = [];
     if (!manifest.namespace.startsWith("@")) {
@@ -63,5 +64,39 @@ export const validateManifest = (manifest) => {
             });
         }
     }
+    const externalDeps = manifest.externalDeps ?? [];
+    const entriesByBasePackage = new Map();
+    for (const entry of externalDeps) {
+        const { basePackage } = splitPackageSpecifier(entry.name);
+        const group = entriesByBasePackage.get(basePackage) ?? [];
+        group.push(entry);
+        entriesByBasePackage.set(basePackage, group);
+    }
+    for (const [basePackage, group] of entriesByBasePackage) {
+        const distinctVersions = new Set(group.map((entry) => entry.version));
+        if (distinctVersions.size > 1) {
+            diagnostics.push({
+                level: "warning",
+                code: "external-deps-version-conflict",
+                message: `externalDeps entries ${group
+                    .map((entry) => `"${entry.name}"@${entry.version}`)
+                    .join(", ")} all resolve to package "${basePackage}" but declare different versions.`,
+            });
+        }
+    }
+    for (const entry of externalDeps) {
+        const peerNames = entry.peerDeps === false
+            ? []
+            : (entry.peerDeps ?? manifest.defaultPeerDeps ?? []);
+        for (const peerName of peerNames) {
+            if (!entriesByBasePackage.has(peerName)) {
+                diagnostics.push({
+                    level: "warning",
+                    code: "external-deps-unresolvable-peer",
+                    message: `externalDeps entry "${entry.name}" lists peer dependency "${peerName}", but no externalDeps entry declares a version for "${peerName}".`,
+                });
+            }
+        }
+    }
     return diagnostics;
 };

package/package.json

@@ -1,7 +1,12 @@
 {
   "name": "@rmc-toolkit/core",
-  "version": "0.1.0",
+  "version": "0.2.3",
   "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/runtime-module-composition/rmc-toolkit",
+    "directory": "packages/core"
+  },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {