@objectstack/types 17.1.0 → 17.3.0

package/dist/node.d.mts

@@ -7,6 +7,32 @@
  * did.
  */
 type HostImporter = (pkg: string) => Promise<any>;
+/**
+ * The importing package's OWN dynamic import — write it literally, in the
+ * calling module:
+ *
+ *     createHostImporter(hostRoot, { fallbackImport: (s) => import(s) })
+ *
+ * `any` for the same reason {@link HostImporter} uses it: the module namespace
+ * belongs to a package this repo does not compile against.
+ */
+type FallbackImport = (specifier: string) => Promise<any>;
+/** Options for {@link createHostImporter}. */
+interface HostImporterOptions {
+    /**
+     * The resolution base for everything the host app does NOT declare — supplied
+     * as the caller's own `import()` rather than as a URL string, because a
+     * string base was MEASURED to be unimplementable without a regression. See
+     * {@link createHostImporter}'s "why a function" note for both measurements.
+     *
+     * Omitted ⇒ the fallback resolves from `@objectstack/types`, which sees only
+     * `@objectstack/types`'s own dependencies. That default is retained so an
+     * out-of-tree caller cannot be broken by this parameter's arrival, and the
+     * `undeclared` failure text names it explicitly so the gap reports itself
+     * instead of being rediscovered.
+     */
+    fallbackImport?: FallbackImport;
+}
 /**
  * A `require` anchored at the **host app's** `package.json` — i.e. the project
  * `objectstack serve` was invoked in, or the app `bootStack` is verifying, whose
@@ -95,10 +121,19 @@ declare function isDeclaredByHost(specifier: string, hostRoot?: string): boolean
  *   in the app and install.
  * - `declared-unresolvable` — the app declares it and it still would not
  *   resolve. Remedy: fix the INSTALL. Re-reading the manifest is wasted effort.
+ * - `declared-no-loadable-entry` (#14041) — the app declares it, the install
+ *   delivered it, and the package's own `exports` names NO entry Node can load
+ *   for the requested subpath — no `require`-condition target (which is why the
+ *   CJS resolution refused) and no `import`-condition one for the fallback
+ *   either (a `types`-only or `browser`-only publish, or a subpath the map
+ *   never names). Remedy: change the PACKAGE — neither the app's manifest nor
+ *   its install can ever fix this, which is exactly why it must not share the
+ *   `declared-unresolvable` INSTALL wording.
  *
- * An evaluation crash is neither: it propagates untouched and carries no kind.
+ * An evaluation crash is none of these: it propagates untouched and carries no
+ * kind.
  */
-type HostImportFailureKind = 'undeclared' | 'declared-unresolvable';
+type HostImportFailureKind = 'undeclared' | 'declared-unresolvable' | 'declared-no-loadable-entry';
 /**
  * Property carrying {@link HostImportFailureKind} on a thrown error.
  *
@@ -123,20 +158,64 @@ declare function hostImportFailureKind(err: unknown): HostImportFailureKind | un
  *    the install is broken. It is not retried bare: falling back there would
  *    reintroduce exactly the "some other package happens to supply it" accident
  *    this gate closes, and would report an install problem as an absence.
- * 3. Undeclared falls back to the importing package's own resolution, which is
- *    what keeps every framework-owned load working (`serve`'s plugin-auth /
- *    service-i18n path, `bootStack`'s service plugins). Bare `import()` is ESM,
- *    and ESM does not honour `NODE_PATH`, so the fallback cannot re-open the
- *    hole either. Only when that fails as module-not-found does the undeclared
- *    error surface; a package that RESOLVES and then throws while evaluating is
- *    a genuine crash and propagates untouched, as before.
+ * 3. Undeclared falls back to the CALLER's own resolution, which is what keeps
+ *    every framework-owned load working (`serve`'s plugin-auth / service-i18n
+ *    path, `bootStack`'s service plugins). Bare `import()` is ESM, and ESM does
+ *    not honour `NODE_PATH`, so the fallback cannot re-open the hole either.
+ *    Only when that fails as module-not-found does the undeclared error
+ *    surface; a package that RESOLVES and then throws while evaluating is a
+ *    genuine crash and propagates untouched, as before.
+ *
+ * ── The caller supplies that base, and why it is a FUNCTION (#10943) ─────────
+ *
+ * Step 3 said "the importing package's own resolution" long before anything
+ * made it true. The fallback was a bare `import()` written HERE, and ESM
+ * resolves a bare specifier against the module containing the call — so it
+ * resolved from `@objectstack/types`, which under a pnpm-isolated layout can
+ * see only `@objectstack/types`'s own dependencies. Measured on `main` from an
+ * app declaring nothing, `@objectstack/plugin-auth`, `@objectstack/plugin-audit`
+ * and `chalk` all resolve from `packages/cli` and all failed through this
+ * helper; `@objectstack/spec` — the one dependency this package declares — was
+ * the only name that came back OK, which is the whole pattern. Under a hoisted
+ * npm/yarn layout the same fallback usually DOES find the caller's
+ * dependencies, so the claim was green in some installs and absent in others:
+ * the layout-dependence class cloud#1013 and #10645 exist to close, one level
+ * up. A declared contract the implementation does not keep is the thing this
+ * repo fixes at the producer (Prime Directive #12), so the mechanism moved
+ * rather than the sentence.
+ *
+ * The base arrives as the caller's own `import()` and NOT as a `parentURL` /
+ * `import.meta.url` string. Both string spellings were measured on Node
+ * v22.22.2 and both are wrong:
+ *
+ *   - `import.meta.resolve(specifier, parentURL)` — the parent argument is
+ *     SILENTLY IGNORED without `--experimental-import-meta-resolve`. Measured:
+ *     resolving `@objectstack/plugin-auth` against a `packages/types` parent
+ *     returned `packages/cli/node_modules/...`, i.e. the caller's own answer,
+ *     byte-identical to passing no parent at all. It would have compiled, run,
+ *     and pinned green while ignoring the base — a phantom fix of exactly the
+ *     kind this card is about.
+ *   - `createRequire(parentURL).resolve(specifier)` — CJS resolution, which
+ *     honours `NODE_PATH`. Measured against a store reachable only through
+ *     `NODE_PATH`: the CJS resolve found it (with and without the `paths`
+ *     option, since GLOBAL_FOLDERS are always appended) while the ESM bare
+ *     `import()` did not. That is #4719's hole re-opened on the fallback path,
+ *     and it would have falsified the "ESM does not honour NODE_PATH" sentence
+ *     three lines above.
+ *
+ * A function written in the calling module is the only spelling that uses
+ * Node's real ESM resolver anchored where the caller actually lives: no flag,
+ * no `NODE_PATH`, no second resolution algorithm to drift from the first.
  *
  * @param hostRoot Directory holding the host app's `package.json` (default: the
  * process CWD, which is where the CLI reads `objectstack.config.ts` from too).
  * Note this used to take a pre-built `NodeRequire`; it needs the ROOT now,
  * because a `NodeRequire` cannot be asked where it was anchored and the manifest
  * has to be read from there.
+ * @param options {@link HostImporterOptions.fallbackImport} carries the caller's
+ * resolution base. Omitting it keeps the pre-#10943 behaviour (this package's
+ * own resolution) so no out-of-tree caller changes under its feet.
  */
-declare function createHostImporter(hostRoot?: string): HostImporter;
+declare function createHostImporter(hostRoot?: string, options?: HostImporterOptions): HostImporter;
 
-export { HOST_DECLARATION_FIELDS, HOST_IMPORT_FAILURE_KIND, type HostDeclaration, type HostDeclarationField, type HostImportFailureKind, type HostImporter, createHostImporter, createHostRequire, hostImportFailureKind, isDeclaredByHost, packageNameFromSpecifier, readHostDeclaration };
+export { type FallbackImport, HOST_DECLARATION_FIELDS, HOST_IMPORT_FAILURE_KIND, type HostDeclaration, type HostDeclarationField, type HostImportFailureKind, type HostImporter, type HostImporterOptions, createHostImporter, createHostRequire, hostImportFailureKind, isDeclaredByHost, packageNameFromSpecifier, readHostDeclaration };

package/dist/node.d.ts

@@ -7,6 +7,32 @@
  * did.
  */
 type HostImporter = (pkg: string) => Promise<any>;
+/**
+ * The importing package's OWN dynamic import — write it literally, in the
+ * calling module:
+ *
+ *     createHostImporter(hostRoot, { fallbackImport: (s) => import(s) })
+ *
+ * `any` for the same reason {@link HostImporter} uses it: the module namespace
+ * belongs to a package this repo does not compile against.
+ */
+type FallbackImport = (specifier: string) => Promise<any>;
+/** Options for {@link createHostImporter}. */
+interface HostImporterOptions {
+    /**
+     * The resolution base for everything the host app does NOT declare — supplied
+     * as the caller's own `import()` rather than as a URL string, because a
+     * string base was MEASURED to be unimplementable without a regression. See
+     * {@link createHostImporter}'s "why a function" note for both measurements.
+     *
+     * Omitted ⇒ the fallback resolves from `@objectstack/types`, which sees only
+     * `@objectstack/types`'s own dependencies. That default is retained so an
+     * out-of-tree caller cannot be broken by this parameter's arrival, and the
+     * `undeclared` failure text names it explicitly so the gap reports itself
+     * instead of being rediscovered.
+     */
+    fallbackImport?: FallbackImport;
+}
 /**
  * A `require` anchored at the **host app's** `package.json` — i.e. the project
  * `objectstack serve` was invoked in, or the app `bootStack` is verifying, whose
@@ -95,10 +121,19 @@ declare function isDeclaredByHost(specifier: string, hostRoot?: string): boolean
  *   in the app and install.
  * - `declared-unresolvable` — the app declares it and it still would not
  *   resolve. Remedy: fix the INSTALL. Re-reading the manifest is wasted effort.
+ * - `declared-no-loadable-entry` (#14041) — the app declares it, the install
+ *   delivered it, and the package's own `exports` names NO entry Node can load
+ *   for the requested subpath — no `require`-condition target (which is why the
+ *   CJS resolution refused) and no `import`-condition one for the fallback
+ *   either (a `types`-only or `browser`-only publish, or a subpath the map
+ *   never names). Remedy: change the PACKAGE — neither the app's manifest nor
+ *   its install can ever fix this, which is exactly why it must not share the
+ *   `declared-unresolvable` INSTALL wording.
  *
- * An evaluation crash is neither: it propagates untouched and carries no kind.
+ * An evaluation crash is none of these: it propagates untouched and carries no
+ * kind.
  */
-type HostImportFailureKind = 'undeclared' | 'declared-unresolvable';
+type HostImportFailureKind = 'undeclared' | 'declared-unresolvable' | 'declared-no-loadable-entry';
 /**
  * Property carrying {@link HostImportFailureKind} on a thrown error.
  *
@@ -123,20 +158,64 @@ declare function hostImportFailureKind(err: unknown): HostImportFailureKind | un
  *    the install is broken. It is not retried bare: falling back there would
  *    reintroduce exactly the "some other package happens to supply it" accident
  *    this gate closes, and would report an install problem as an absence.
- * 3. Undeclared falls back to the importing package's own resolution, which is
- *    what keeps every framework-owned load working (`serve`'s plugin-auth /
- *    service-i18n path, `bootStack`'s service plugins). Bare `import()` is ESM,
- *    and ESM does not honour `NODE_PATH`, so the fallback cannot re-open the
- *    hole either. Only when that fails as module-not-found does the undeclared
- *    error surface; a package that RESOLVES and then throws while evaluating is
- *    a genuine crash and propagates untouched, as before.
+ * 3. Undeclared falls back to the CALLER's own resolution, which is what keeps
+ *    every framework-owned load working (`serve`'s plugin-auth / service-i18n
+ *    path, `bootStack`'s service plugins). Bare `import()` is ESM, and ESM does
+ *    not honour `NODE_PATH`, so the fallback cannot re-open the hole either.
+ *    Only when that fails as module-not-found does the undeclared error
+ *    surface; a package that RESOLVES and then throws while evaluating is a
+ *    genuine crash and propagates untouched, as before.
+ *
+ * ── The caller supplies that base, and why it is a FUNCTION (#10943) ─────────
+ *
+ * Step 3 said "the importing package's own resolution" long before anything
+ * made it true. The fallback was a bare `import()` written HERE, and ESM
+ * resolves a bare specifier against the module containing the call — so it
+ * resolved from `@objectstack/types`, which under a pnpm-isolated layout can
+ * see only `@objectstack/types`'s own dependencies. Measured on `main` from an
+ * app declaring nothing, `@objectstack/plugin-auth`, `@objectstack/plugin-audit`
+ * and `chalk` all resolve from `packages/cli` and all failed through this
+ * helper; `@objectstack/spec` — the one dependency this package declares — was
+ * the only name that came back OK, which is the whole pattern. Under a hoisted
+ * npm/yarn layout the same fallback usually DOES find the caller's
+ * dependencies, so the claim was green in some installs and absent in others:
+ * the layout-dependence class cloud#1013 and #10645 exist to close, one level
+ * up. A declared contract the implementation does not keep is the thing this
+ * repo fixes at the producer (Prime Directive #12), so the mechanism moved
+ * rather than the sentence.
+ *
+ * The base arrives as the caller's own `import()` and NOT as a `parentURL` /
+ * `import.meta.url` string. Both string spellings were measured on Node
+ * v22.22.2 and both are wrong:
+ *
+ *   - `import.meta.resolve(specifier, parentURL)` — the parent argument is
+ *     SILENTLY IGNORED without `--experimental-import-meta-resolve`. Measured:
+ *     resolving `@objectstack/plugin-auth` against a `packages/types` parent
+ *     returned `packages/cli/node_modules/...`, i.e. the caller's own answer,
+ *     byte-identical to passing no parent at all. It would have compiled, run,
+ *     and pinned green while ignoring the base — a phantom fix of exactly the
+ *     kind this card is about.
+ *   - `createRequire(parentURL).resolve(specifier)` — CJS resolution, which
+ *     honours `NODE_PATH`. Measured against a store reachable only through
+ *     `NODE_PATH`: the CJS resolve found it (with and without the `paths`
+ *     option, since GLOBAL_FOLDERS are always appended) while the ESM bare
+ *     `import()` did not. That is #4719's hole re-opened on the fallback path,
+ *     and it would have falsified the "ESM does not honour NODE_PATH" sentence
+ *     three lines above.
+ *
+ * A function written in the calling module is the only spelling that uses
+ * Node's real ESM resolver anchored where the caller actually lives: no flag,
+ * no `NODE_PATH`, no second resolution algorithm to drift from the first.
  *
  * @param hostRoot Directory holding the host app's `package.json` (default: the
  * process CWD, which is where the CLI reads `objectstack.config.ts` from too).
  * Note this used to take a pre-built `NodeRequire`; it needs the ROOT now,
  * because a `NodeRequire` cannot be asked where it was anchored and the manifest
  * has to be read from there.
+ * @param options {@link HostImporterOptions.fallbackImport} carries the caller's
+ * resolution base. Omitting it keeps the pre-#10943 behaviour (this package's
+ * own resolution) so no out-of-tree caller changes under its feet.
  */
-declare function createHostImporter(hostRoot?: string): HostImporter;
+declare function createHostImporter(hostRoot?: string, options?: HostImporterOptions): HostImporter;
 
-export { HOST_DECLARATION_FIELDS, HOST_IMPORT_FAILURE_KIND, type HostDeclaration, type HostDeclarationField, type HostImportFailureKind, type HostImporter, createHostImporter, createHostRequire, hostImportFailureKind, isDeclaredByHost, packageNameFromSpecifier, readHostDeclaration };
+export { type FallbackImport, HOST_DECLARATION_FIELDS, HOST_IMPORT_FAILURE_KIND, type HostDeclaration, type HostDeclarationField, type HostImportFailureKind, type HostImporter, type HostImporterOptions, createHostImporter, createHostRequire, hostImportFailureKind, isDeclaredByHost, packageNameFromSpecifier, readHostDeclaration };

package/dist/node.js

@@ -87,7 +87,7 @@ function isDeclaredByHost(specifier, hostRoot) {
 var HOST_IMPORT_FAILURE_KIND = "objectstackHostImportFailureKind";
 function hostImportFailureKind(err) {
   const kind = err?.[HOST_IMPORT_FAILURE_KIND];
-  return kind === "undeclared" || kind === "declared-unresolvable" ? kind : void 0;
+  return kind === "undeclared" || kind === "declared-unresolvable" || kind === "declared-no-loadable-entry" ? kind : void 0;
 }
 function hostImportError(kind, message, cause) {
   const err = new Error(message);
@@ -97,9 +97,10 @@ function hostImportError(kind, message, cause) {
     [HOST_IMPORT_FAILURE_KIND]: kind
   });
 }
-function undeclaredMessage(declaration, cause) {
+function undeclaredMessage(declaration, cause, callerBaseSupplied) {
   const { packageName, hostRoot, manifestMissing } = declaration;
   const detail = cause instanceof Error ? cause.message : String(cause);
+  const baseNote = callerBaseSupplied ? "" : "\n  (the caller did not pass `fallbackImport`, so that fallback resolved from\n  @objectstack/types, which can see only its own dependencies \u2014 a caller that\n  needs its own resolution passes `{ fallbackImport: (s) => import(s) }`, #10943)";
   return `Cannot find package '${packageName}': the host app does not declare it.
   host app: ${hostRoot}
 ` + (manifestMissing ? "  no readable package.json was found there \u2014 nothing can be declared\n" : `  checked: ${HOST_DECLARATION_FIELDS.join(", ")}
@@ -112,7 +113,7 @@ function undeclaredMessage(declaration, cause) {
   at in every pnpm bin shim \u2014 used to resolve here regardless of the app's
   package.json, so the same app booted or refused depending on how the
   process was launched. The declaration is the contract.
-  (fallback resolution also failed: ${detail})`;
+  (fallback resolution also failed: ${detail})${baseNote}`;
 }
 function unresolvableMessage(declaration, cause) {
   const { packageName, hostRoot, field, specifier } = declaration;
@@ -128,8 +129,192 @@ function unresolvableMessage(declaration, cause) {
     \u2022 it IS installed but its "main"/"exports" points at a dist that was never built
   (resolver: ${detail})`;
 }
-function createHostImporter(hostRoot = process.cwd()) {
+var ESM_IMPORT_CONDITIONS = /* @__PURE__ */ new Set([
+  "node-addons",
+  "node",
+  "import",
+  "default"
+]);
+var CJS_REQUIRE_CONDITIONS = /* @__PURE__ */ new Set([
+  "node-addons",
+  "node",
+  "require",
+  "default"
+]);
+function selectConditionTarget(node, conditions) {
+  if (typeof node === "string") return node;
+  if (Array.isArray(node)) {
+    for (const alternative of node) {
+      const hit = selectConditionTarget(alternative, conditions);
+      if (hit !== void 0) return hit;
+    }
+    return void 0;
+  }
+  if (node === null || typeof node !== "object") return void 0;
+  for (const entry of Object.entries(node)) {
+    if (!conditions.has(entry[0])) continue;
+    const hit = selectConditionTarget(entry[1], conditions);
+    if (hit !== void 0) return hit;
+  }
+  return void 0;
+}
+function resolveExportsSubpath(exportsField, subpath, conditions = ESM_IMPORT_CONDITIONS) {
+  if (exportsField === void 0) return void 0;
+  const keys = typeof exportsField === "object" && exportsField !== null && !Array.isArray(exportsField) ? Object.keys(exportsField) : void 0;
+  const isSubpathMap = keys !== void 0 && keys.length > 0 && keys.every((key) => key === "." || key.indexOf("./") === 0);
+  if (!isSubpathMap) {
+    return subpath === "." ? selectConditionTarget(exportsField, conditions) : void 0;
+  }
+  const map = exportsField;
+  if (Object.prototype.hasOwnProperty.call(map, subpath)) {
+    return selectConditionTarget(map[subpath], conditions);
+  }
+  let best;
+  for (const entry of Object.entries(map)) {
+    const star = entry[0].indexOf("*");
+    if (star < 0 || entry[0].indexOf("*", star + 1) >= 0) continue;
+    const prefix = entry[0].slice(0, star);
+    const suffix = entry[0].slice(star + 1);
+    if (subpath.indexOf(prefix) !== 0) continue;
+    if (suffix !== "" && subpath.slice(subpath.length - suffix.length) !== suffix) continue;
+    if (subpath.length < prefix.length + suffix.length) continue;
+    if (best !== void 0 && (best.prefix.length > prefix.length || best.prefix.length === prefix.length && best.suffix.length >= suffix.length)) {
+      continue;
+    }
+    best = { prefix, suffix, target: entry[1] };
+  }
+  if (best === void 0) return void 0;
+  const matched = subpath.slice(best.prefix.length, subpath.length - best.suffix.length);
+  const target = selectConditionTarget(best.target, conditions);
+  return target === void 0 ? void 0 : target.split("*").join(matched);
+}
+function exportsSubpathOf(specifier, packageName) {
+  return specifier === packageName ? "." : `.${specifier.slice(packageName.length)}`;
+}
+function packageRootOf(resolvedFile, packageName) {
+  let dir = (0, import_node_path.dirname)(resolvedFile);
+  for (let hop = 0; hop < 64; hop += 1) {
+    try {
+      const manifest = JSON.parse((0, import_node_fs.readFileSync)((0, import_node_path.join)(dir, "package.json"), "utf8"));
+      if (manifest.name === packageName) return dir;
+    } catch {
+    }
+    const parent = (0, import_node_path.dirname)(dir);
+    if (parent === dir) return void 0;
+    dir = parent;
+  }
+  return void 0;
+}
+function esmEntryForDeclared(specifier, packageName, cjsResolved) {
+  const root = packageRootOf(cjsResolved, packageName);
+  if (root === void 0) return void 0;
+  let exportsField;
+  try {
+    exportsField = JSON.parse((0, import_node_fs.readFileSync)((0, import_node_path.join)(root, "package.json"), "utf8")).exports;
+  } catch {
+    return void 0;
+  }
+  if (exportsField === void 0 || exportsField === null) return void 0;
+  const subpath = exportsSubpathOf(specifier, packageName);
+  const target = resolveExportsSubpath(exportsField, subpath);
+  if (typeof target !== "string" || target.indexOf("./") !== 0) return void 0;
+  const entry = (0, import_node_path.resolve)(root, target);
+  if (entry.indexOf(root + import_node_path.sep) !== 0) return void 0;
+  return (0, import_node_fs.existsSync)(entry) ? entry : void 0;
+}
+function hasInvalidExportsSubpathSegments(subpath) {
+  if (subpath === ".") return false;
+  return subpath.slice(2).split(/[/\\]/).some((raw) => {
+    const segment = raw.toLowerCase();
+    return segment === "" || segment === "." || segment === ".." || segment === "node_modules";
+  });
+}
+var ALIAS_DECLARATION_PROTOCOLS = [
+  { prefix: "npm:", rangeRequired: false },
+  { prefix: "workspace:", rangeRequired: true }
+];
+function declaredManifestName(declaration) {
+  const { packageName, specifier } = declaration;
+  if (specifier === void 0) return packageName;
+  const protocol = ALIAS_DECLARATION_PROTOCOLS.find((p) => specifier.indexOf(p.prefix) === 0);
+  if (protocol === void 0) return packageName;
+  const value = specifier.slice(protocol.prefix.length);
+  const at = value.lastIndexOf("@");
+  if (at <= 0 && protocol.rangeRequired) return packageName;
+  const name = at > 0 ? value.slice(0, at) : value;
+  return packageNameFromSpecifier(name) === name ? name : packageName;
+}
+function hostInstalledPackageDir(declaration) {
+  const { packageName, hostRoot } = declaration;
+  const linked = (0, import_node_path.join)(hostRoot, "node_modules", ...packageName.split("/"));
+  try {
+    const manifest = JSON.parse((0, import_node_fs.readFileSync)((0, import_node_path.join)(linked, "package.json"), "utf8"));
+    if (manifest.name !== declaredManifestName(declaration)) return void 0;
+  } catch {
+    return void 0;
+  }
+  try {
+    return (0, import_node_fs.realpathSync)(linked);
+  } catch {
+    return linked;
+  }
+}
+function declaredCjsResolveFallback(specifier, declaration) {
+  const { packageName } = declaration;
+  const packageDir = hostInstalledPackageDir(declaration);
+  if (packageDir === void 0) return { outcome: "absent" };
+  let exportsField;
+  try {
+    exportsField = JSON.parse((0, import_node_fs.readFileSync)((0, import_node_path.join)(packageDir, "package.json"), "utf8")).exports;
+  } catch {
+    return { outcome: "absent" };
+  }
+  if (exportsField === void 0 || exportsField === null) return { outcome: "install-broken" };
+  const subpath = exportsSubpathOf(specifier, packageName);
+  if (hasInvalidExportsSubpathSegments(subpath)) return { outcome: "invalid-specifier" };
+  const importTarget = resolveExportsSubpath(exportsField, subpath, ESM_IMPORT_CONDITIONS);
+  if (typeof importTarget === "string" && importTarget.indexOf("./") === 0) {
+    const entry = (0, import_node_path.resolve)(packageDir, importTarget);
+    if (entry.indexOf(packageDir + import_node_path.sep) === 0 && (0, import_node_fs.existsSync)(entry)) {
+      return { outcome: "entry", entry };
+    }
+    return { outcome: "install-broken" };
+  }
+  const requireTarget = resolveExportsSubpath(exportsField, subpath, CJS_REQUIRE_CONDITIONS);
+  if (typeof requireTarget === "string" && requireTarget.indexOf("./") === 0) {
+    return { outcome: "install-broken" };
+  }
+  return { outcome: "no-loadable-entry", packageDir };
+}
+function noLoadableEntryMessage(declaration, packageDir, subpath, cause) {
+  const { packageName, hostRoot, field, specifier } = declaration;
+  const detail = cause instanceof Error ? cause.message : String(cause);
+  const subpathNote = subpath === "." ? 'its main entry (".")' : `the subpath '${subpath}'`;
+  return `Cannot load module '${packageName}': the host app DECLARES it (${field}: ${JSON.stringify(specifier)}) and it IS installed, but the package publishes no entry that Node can load.
+  host app: ${hostRoot}
+  installed at: ${packageDir}
+
+  This is a problem with the PACKAGE's own published shape, not with the app or
+  its install \u2014 the declaration is right and the package is on disk, so neither
+  re-reading package.json nor re-running \`pnpm install\` can change anything.
+  Measured from its manifest:
+    \u2022 its "exports" map names no \`require\`-condition entry for ${subpathNote},
+      so a CommonJS resolution cannot see it at all
+    \u2022 and no \`import\`-condition entry either, so there is nothing for the ESM
+      fallback to load
+  The remedy lives in the package: it must publish a runtime entry for this
+  subpath (an \`import\` condition suffices here; a dual build adds \`require\`).
+  A publish carrying only \`types\` / \`browser\`-style conditions cannot be loaded
+  by a Node host at all.
+  (resolver: ${detail})`;
+}
+function createHostImporter(hostRoot = process.cwd(), options = {}) {
   const hostRequire = createHostRequire(hostRoot);
+  const { fallbackImport } = options;
+  const importAsCaller = fallbackImport ?? ((specifier) => import(
+    /* webpackIgnore: true */
+    specifier
+  ));
   return async (pkg) => {
     if (packageNameFromSpecifier(pkg) === void 0) {
       return import(
@@ -143,22 +328,40 @@ function createHostImporter(hostRoot = process.cwd()) {
       try {
         resolved = hostRequire.resolve(pkg);
       } catch (cause) {
+        const fallback = declaredCjsResolveFallback(pkg, declaration);
+        if (fallback.outcome === "entry") {
+          return import((0, import_node_url.pathToFileURL)(fallback.entry).href);
+        }
+        if (fallback.outcome === "no-loadable-entry") {
+          throw hostImportError(
+            "declared-no-loadable-entry",
+            noLoadableEntryMessage(
+              declaration,
+              fallback.packageDir,
+              exportsSubpathOf(pkg, declaration.packageName),
+              cause
+            ),
+            cause
+          );
+        }
         throw hostImportError(
           "declared-unresolvable",
           unresolvableMessage(declaration, cause),
           cause
         );
       }
-      return import((0, import_node_url.pathToFileURL)(resolved).href);
+      const entry = esmEntryForDeclared(pkg, declaration.packageName, resolved) ?? resolved;
+      return import((0, import_node_url.pathToFileURL)(entry).href);
     }
     try {
-      return await import(
-        /* webpackIgnore: true */
-        pkg
-      );
+      return await importAsCaller(pkg);
     } catch (cause) {
       if (!isModuleNotFoundError(cause)) throw cause;
-      throw hostImportError("undeclared", undeclaredMessage(declaration, cause), cause);
+      throw hostImportError(
+        "undeclared",
+        undeclaredMessage(declaration, cause, fallbackImport !== void 0),
+        cause
+      );
     }
   };
 }