@uniweb/build 0.16.23 → 0.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.16.23",
+  "version": "0.17.0",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -61,14 +61,14 @@
     "yaml": "^2.5.0",
     "@uniweb/schemas": "0.2.10",
     "@uniweb/theming": "0.1.15",
-    "@uniweb/projections": "0.2.5",
-    "@uniweb/content-writer": "0.3.3"
+    "@uniweb/content-writer": "0.3.3",
+    "@uniweb/projections": "0.2.5"
   },
   "optionalDependencies": {
+    "@uniweb/runtime": "0.10.0",
     "@uniweb/schemas": "0.2.10",
-    "@uniweb/content-reader": "1.2.2",
-    "@uniweb/runtime": "0.9.10",
-    "@uniweb/semantic-parser": "1.2.1"
+    "@uniweb/semantic-parser": "1.2.1",
+    "@uniweb/content-reader": "1.2.2"
   },
   "peerDependencies": {
     "vite": "^5.0.0 || ^6.0.0 || ^7.0.0",

package/src/import-map-plugin.js

@@ -31,11 +31,52 @@ const IMPORT_MAP_PREFIX = '\0importmap:'
 /** Valid JS identifier — filters out non-identifier keys from CJS modules */
 const isValidId = (k) => /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(k)
 
+/**
+ * An external may be a bare specifier string, or an object declaring its
+ * surface explicitly.
+ *
+ * ⛔ WHY THE OBJECT FORM EXISTS — read before "simplifying" it away.
+ *
+ * The string form enumerates a module's exports by `await import(pkg)` in the
+ * Vite process, i.e. in NODE. That works for plain `.js`, and **throws for
+ * anything reached through a `.jsx` file** — Node cannot parse JSX. The catch
+ * below then falls back to `export * from pkg`, and `export *` **never
+ * re-exports `default`**. So a bridged module whose public surface IS its
+ * default export silently emits a bridge with that export missing.
+ *
+ * Measured 2026-08-08 on `@uniweb/runtime/provider` (whose only export is
+ * `export default function RuntimeProvider`): the fallback produced ZERO
+ * exports, so Rollup reused the emitted filename as a shared chunk and the
+ * "bridge" shipped containing `ErrorBoundary` instead. The file existed, the
+ * manifest listed it, the channel published it and its digests verified — and
+ * `import RuntimeProvider from '<bridge>'` throws "does not provide an export
+ * named 'default'". Nothing upstream of the browser could see it.
+ *
+ * `hasDefault` is what `export *` cannot express, so it is the one thing worth
+ * declaring. Named exports stay self-maintaining through `export *`.
+ *
+ * @typedef {string | { spec: string, hasDefault?: boolean, named?: string[] }} External
+ */
+const specOf = (e) => (typeof e === 'string' ? e : e.spec)
+
+/**
+ * The bridge filename for a specifier: `@uniweb/runtime/provider` →
+ * `@uniweb-runtime-provider.js`.
+ *
+ * Exported because THREE producers must agree on it — the emitted chunk, the
+ * `<script type="importmap">`, and the runtime shell's `manifest.json`. A
+ * consumer resolves a bridge by the manifest's URL, so a manifest that names a
+ * file the build did not emit is a 404 at import time, not a build error.
+ */
+export const bridgeFileName = (spec) => `${spec.replace(/\//g, '-')}.js`
+
 /**
  * Create the import map Vite plugin.
  *
  * @param {Object} [options]
- * @param {string[]} [options.externals] - Package specifiers to bridge (default: react, react-dom, @uniweb/core, etc.)
+ * @param {External[]} [options.externals] - Specifiers to bridge (default: react, react-dom, @uniweb/core, etc.).
+ *   Each entry is a bare specifier string, or `{ spec, hasDefault?, named? }` when the module's
+ *   surface cannot be enumerated by importing it in Node — see the `External` typedef.
  * @param {string} [options.name] - Plugin name (default: 'uniweb:import-map')
  * @param {string} [options.basePath] - Base path prefix for import map URLs in HTML (default: '/')
  * @param {string} [options.resolveFrom] - Absolute path to resolve bare specifiers from inside virtual modules.
@@ -68,7 +109,7 @@ export function importMapPlugin({
       // from '\0importmap:@uniweb/core') can't be resolved by Rollup because virtual
       // modules have no filesystem context. When a resolveFrom path is provided,
       // resolve from there (e.g. the foundation directory under pnpm strict mode).
-      if (resolveFrom && importer?.startsWith(IMPORT_MAP_PREFIX) && externals.includes(id)) {
+      if (resolveFrom && importer?.startsWith(IMPORT_MAP_PREFIX) && externals.some((e) => specOf(e) === id)) {
         return this.resolve(id, resolveFrom, { skipSelf: true })
       }
     },
@@ -76,6 +117,24 @@ export function importMapPlugin({
     async load(id) {
       if (!id.startsWith(IMPORT_MAP_PREFIX)) return
       const pkg = id.slice(IMPORT_MAP_PREFIX.length)
+      const declared = externals.find((e) => specOf(e) === pkg)
+
+      // A declared surface wins outright — no Node import is attempted, so a
+      // JSX-reaching module is bridged correctly instead of falling into the
+      // lossy catch below. See the `External` typedef for why this exists.
+      if (typeof declared === 'object' && (declared.named || declared.hasDefault !== undefined)) {
+        const lines = []
+        if (declared.named?.length) {
+          lines.push(`export { ${declared.named.join(', ')} } from '${pkg}'`)
+        } else {
+          // Named exports stay self-maintaining; only `default` is declared.
+          lines.push(`export * from '${pkg}'`)
+        }
+        if (declared.hasDefault) {
+          lines.push(`export { default } from '${pkg}'`)
+        }
+        return lines.join('\n')
+      }
 
       // Generate explicit named re-exports (not `export *`) because CJS
       // packages like React only expose a default via `export *`, losing
@@ -93,8 +152,17 @@ export function importMapPlugin({
           lines.push(`export { default } from '${pkg}'`)
         }
         return lines.join('\n') || 'export {}'
-      } catch {
-        // Fallback: generic re-export (may not preserve named exports for CJS)
+      } catch (err) {
+        // Loud, because this fallback CANNOT carry a default export. Staying
+        // silent here is what let a bridge ship with its only export missing
+        // (see the `External` typedef). If the module has a default, declare
+        // `{ spec, hasDefault: true }`; if it genuinely has none, declare
+        // `{ spec, hasDefault: false }` to assert that and silence this.
+        this.warn(
+          `[import-map] could not enumerate "${pkg}" (${err.message.split('\n')[0]}). ` +
+            `Falling back to \`export *\`, which DROPS a default export. ` +
+            `Declare it as { spec: '${pkg}', hasDefault: true|false } to be explicit.`
+        )
         return `export * from '${pkg}'`
       }
     },
@@ -105,10 +173,11 @@ export function importMapPlugin({
     buildStart() {
       if (!isBuild) return
       for (const ext of externals) {
+        const spec = specOf(ext)
         this.emitFile({
           type: 'chunk',
-          id: `${IMPORT_MAP_PREFIX}${ext}`,
-          fileName: `_importmap/${ext.replace(/\//g, '-')}.js`,
+          id: `${IMPORT_MAP_PREFIX}${spec}`,
+          fileName: `_importmap/${bridgeFileName(spec)}`,
           preserveSignature: 'exports-only',
         })
       }
@@ -125,7 +194,8 @@ export function importMapPlugin({
 
         if (isBuild) {
           for (const ext of externals) {
-            imports[ext] = `${basePath}_importmap/${ext.replace(/\//g, '-')}.js`
+            const spec = specOf(ext)
+            imports[spec] = `${basePath}_importmap/${bridgeFileName(spec)}`
           }
         } else if (devBridges) {
           Object.assign(imports, devBridges)