feat(bundler): implement policy for external import specifiers in bundling process

- Introduced a new policy to handle external import specifiers, ensuring they remain unchanged in bundled output to maintain compatibility across Deno, Node.js, and Bun.
- Updated the Rolldown backend and import map resolver to support explicit external marking and prevent rewriting of bare specifiers.
- Enhanced bundler configuration to allow for explicit externals, improving module instance sharing and reducing potential runtime issues.

Author: eser

etc/adrs/0002-bundler-external-import-specifiers.md

@@ -0,0 +1,226 @@
+# Bundler External Import Specifiers Policy
+
+## Status
+
+Accepted
+
+## Context and Problem Statement
+
+When bundling JavaScript/TypeScript code, some imports are marked as "external"
+(not inlined into the bundle). The bundler must decide what import specifier to
+use in the output for these external imports.
+
+```typescript
+// Source file (with import map resolving @foo/bar to jsr:@foo/bar@^1.0.0)
+import { something } from "@foo/bar";
+
+// Bundled output - what specifier should appear?
+import { something } from "???";
+```
+
+The bundler has access to the project's import map and can resolve bare
+specifiers to their full forms (e.g., `jsr:@foo/bar@^1.0.0`). The question is:
+**should it rewrite the specifier or keep it as-is?**
+
+## Decision Drivers
+
+- **Cross-runtime compatibility**: Output must work in Deno, Node.js, and Bun
+- **Standard resolution**: Use resolution mechanisms all runtimes understand
+- **No runtime dependencies on import maps**: Bundled code should not require
+  import maps to be present at runtime
+- **Simplicity**: Avoid unnecessary transformations
+
+## Decision Outcome
+
+**NEVER rewrite external import specifiers to protocol-specific forms.**
+
+Keep bare specifiers as-is. They resolve from `node_modules` at runtime, which
+works in all JavaScript runtimes.
+
+### The Rule
+
+| Source Specifier | Bundled Output        | Correct? |
+| ---------------- | --------------------- | -------- |
+| `@foo/bar`       | `@foo/bar`            | ✅ YES   |
+| `@foo/bar`       | `jsr:@foo/bar@^1.0.0` | ❌ NO    |
+| `@foo/bar`       | `npm:@foo/bar`        | ❌ NO    |
+| `lodash`         | `lodash`              | ✅ YES   |
+| `lodash`         | `npm:lodash@^4.0.0`   | ❌ NO    |
+
+### Why Protocol Specifiers Break
+
+```typescript
+// This ONLY works in Deno
+import { x } from "jsr:@foo/bar@^1.0.0";
+
+// This ONLY works in Deno
+import { x } from "npm:lodash@^4.0.0";
+
+// This works EVERYWHERE (Deno, Node.js, Bun)
+import { x } from "@foo/bar";
+import { y } from "lodash";
+```
+
+- `jsr:` protocol - Deno-only, not understood by Node.js or Bun
+- `npm:` protocol - Deno-only, not understood by Node.js or Bun
+- Bare specifiers - Standard, resolved from `node_modules` by all runtimes
+
+### Consequences
+
+#### Good
+
+- Bundled code works in Deno, Node.js, and Bun
+- Uses standard `node_modules` resolution
+- No special runtime configuration needed
+- Simpler bundler logic (no specifier rewriting)
+
+#### Bad
+
+- Requires dependencies to be installed in `node_modules`
+- Bare specifiers are less explicit about versions
+
+## Implementation
+
+### In Rolldown Backend (`@eser/bundler`)
+
+Convert external package names to regex patterns for prefix matching:
+
+```typescript
+// In rolldown.ts - bundle() and watch()
+const externalPatterns = config.external?.map((pkg) => {
+  const escaped = pkg.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return new RegExp(`^${escaped}(\\/.*)?$`);
+});
+
+const bundle = await rolldown.rolldown({
+  input: config.entrypoints,
+  external: externalPatterns, // Regex patterns, not strings
+  plugins,
+});
+```
+
+This ensures `"@eser/laroux-server"` matches both:
+
+- `@eser/laroux-server` (exact)
+- `@eser/laroux-server/action-registry` (subpath)
+
+### In Import Map Resolver Plugin
+
+Handle `{ external: true }` without a path in the resolveId hook:
+
+```typescript
+// In rolldown.ts - adaptPlugins()
+if (result?.path !== undefined || result?.external === true) {
+  return {
+    id: result.path ?? source, // Keep original specifier if no path
+    external: result.external,
+  };
+}
+```
+
+Use `autoMarkExternal` option to control automatic external marking:
+
+```typescript
+// For client bundling (default): autoMarkExternal = true
+// For server bundling: autoMarkExternal = false (use explicit externals)
+createImportMapResolverPlugin({
+  projectRoot,
+  browserShims: { jsr: {}, nodeBuiltins: {} },
+  autoMarkExternal: false, // Don't auto-mark npm/jsr as external
+});
+```
+
+### In Bundler Configuration
+
+When specifying externals, use the package name (not subpaths):
+
+```typescript
+// CORRECT - package name covers all subpath imports via regex
+externals: ["@eser/laroux-server", "react", "lodash"];
+
+// The output will have:
+// import { registerAction } from "@eser/laroux-server/action-registry";
+// import { something } from "@eser/laroux-server/other";
+// import React from "react";
+// import _ from "lodash";
+```
+
+## How Bare Specifiers Resolve at Runtime
+
+All runtimes resolve bare specifiers by looking in `node_modules`:
+
+```
+project/
+├── node_modules/
+│   ├── @eser/
+│   │   └── laroux-server/    ← @eser/laroux-server resolves here
+│   ├── react/                 ← react resolves here
+│   └── lodash/                ← lodash resolves here
+├── dist/
+│   └── bundle.js              ← bundled code with bare imports
+├── deno.json                  ← nodeModulesDir: "auto" for Deno
+└── package.json               ← dependencies for npm/bun
+```
+
+**Deno**: With `"nodeModulesDir": "auto"` in `deno.json`, Deno creates
+`node_modules` from JSR/npm dependencies and uses it for resolution.
+
+**Node.js**: Standard `node_modules` resolution per Node.js module algorithm.
+
+**Bun**: Standard `node_modules` resolution, compatible with Node.js.
+
+## Common Mistakes
+
+### Mistake 1: Rewriting to JSR specifiers
+
+```typescript
+// Source
+import { foo } from "@eser/something";
+
+// WRONG output - breaks Node.js and Bun
+import { foo } from "jsr:@eser/something@^4.0.0";
+```
+
+### Mistake 2: Rewriting to npm specifiers
+
+```typescript
+// Source
+import { foo } from "lodash";
+
+// WRONG output - breaks Node.js and Bun
+import { foo } from "npm:lodash@^4.0.0";
+```
+
+### Mistake 3: Using resolved paths for externals
+
+```typescript
+// In resolver plugin
+const resolved = importMap.resolve(specifier); // "jsr:@foo/bar@^1.0.0"
+return { path: resolved, external: true }; // ❌ WRONG
+
+// Correct
+return { external: true }; // ✅ Keeps original bare specifier
+```
+
+## Applies To
+
+This policy applies to ALL bundling operations in the stack:
+
+- **Client bundling** (`bundle()` in `domain/bundler.ts`)
+- **Server bundling** (`bundleServerComponents()` in `domain/bundler.ts`)
+- **Any future bundling** operations
+
+## Related Files
+
+- `pkg/@eser/bundler/backends/rolldown.ts` - Rolldown backend (external regex
+  patterns)
+- `pkg/@eser/laroux-bundler/import-map-resolver-plugin.ts` - Import resolution
+  (autoMarkExternal)
+- `pkg/@eser/laroux-bundler/system.ts` - Build system (server bundling config)
+- `pkg/@eser/laroux-bundler/domain/bundler.ts` - Bundler functions
+
+## Links
+
+- [Deno nodeModulesDir](https://docs.deno.com/runtime/manual/node/npm_specifiers)
+- [Node.js Module Resolution](https://nodejs.org/api/modules.html)
+- [Bun Module Resolution](https://bun.sh/docs/runtime/modules)

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eser/stack",
-  "version": "4.0.33",
+  "version": "4.0.34",
   "private": true,
   "type": "module",
   "workspaces": [

pkg/@cool/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cool/cli",
-  "version": "4.0.33",
+  "version": "4.0.34",
   "type": "module",
   "exports": {
     ".": "./mod.ts"

pkg/@cool/lime/deno.json

@@ -1,6 +1,6 @@
 {
   "name": "@cool/lime",
-  "version": "4.0.33",
+  "version": "4.0.34",
   "exports": {
     ".": "./mod.ts"
   }

pkg/@cool/lime/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cool/lime",
-  "version": "4.0.33",
+  "version": "4.0.34",
   "type": "module",
   "exports": {
     ".": "./mod.ts"

pkg/@eser/app-runtime/deno.json

@@ -1,6 +1,6 @@
 {
   "name": "@eser/app-runtime",
-  "version": "4.0.33",
+  "version": "4.0.34",
   "exports": {
     ".": "./mod.ts"
   },

pkg/@eser/app-runtime/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eser/app-runtime",
-  "version": "4.0.33",
+  "version": "4.0.34",
   "type": "module",
   "exports": {
     ".": "./mod.ts"

pkg/@eser/bundler/backends/rolldown.ts

@@ -370,9 +370,12 @@ export class RolldownBackend implements Bundler {
               namespace: resolver.options.namespace ?? "file",
               kind: "import-statement",
             });
-            if (result?.path !== undefined) {
+            // Handle both path resolution and external marking
+            // External without path keeps original specifier (bare import from node_modules)
+            // See ADR: 0002-bundler-external-import-specifiers.md
+            if (result?.path !== undefined || result?.external === true) {
               return {
-                id: result.path,
+                id: result.path ?? source,
                 external: result.external,
               };
             }

pkg/@eser/bundler/deno.json

@@ -1,6 +1,6 @@
 {
   "name": "@eser/bundler",
-  "version": "4.0.33",
+  "version": "4.0.34",
   "exports": {
     ".": "./mod.ts",
     "./types": "./types.ts",

pkg/@eser/bundler/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eser/bundler",
-  "version": "4.0.33",
+  "version": "4.0.34",
   "type": "module",
   "exports": {
     ".": "./mod.ts"