@uniweb/unipress 0.4.26 → 0.4.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/unipress",
-  "version": "0.4.26",
+  "version": "0.4.28",
   "description": "Compile a content directory into a document (PDF, EPUB, Paged.js HTML, Typst source bundle, DOCX, XLSX) using a Uniweb foundation. Five built-in templates: book, monograph, report, data-report, directory.",
   "type": "module",
   "publishConfig": {
@@ -49,11 +49,11 @@
     "prompts": "^2.4.2",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
-    "@uniweb/core": "0.7.14",
-    "@uniweb/build": "0.14.19",
     "@uniweb/content-reader": "1.1.12",
-    "@uniweb/semantic-parser": "1.1.17",
-    "@uniweb/runtime": "0.8.20"
+    "@uniweb/build": "0.14.20",
+    "@uniweb/core": "0.7.14",
+    "@uniweb/runtime": "0.8.20",
+    "@uniweb/semantic-parser": "1.1.17"
   },
   "devDependencies": {
     "vitest": "^4.1.7"

package/src/foundation-fetch.js

@@ -31,27 +31,11 @@
 // field and this module will verify bytes before caching.
 
 import { existsSync } from 'node:fs'
-import { mkdir, writeFile, symlink } from 'node:fs/promises'
-import { dirname, join, posix, resolve as pathResolve } from 'node:path'
-import { createRequire } from 'node:module'
-import { fileURLToPath } from 'node:url'
+import { mkdir, writeFile } from 'node:fs/promises'
+import { dirname, join, posix } from 'node:path'
 import { FoundationFetchError } from './errors.js'
 import { getCacheDir } from './typst/binary-manager.js'
-
-const require = createRequire(import.meta.url)
-
-// Bare specifiers that the foundation expects to resolve externally
-// (matches DEFAULT_EXTERNALS in @uniweb/build). At import time, Node
-// walks up from the cache dir looking for a node_modules/<name>. The
-// cache dir isn't inside any package tree, so we link unipress's own
-// installations into a co-located node_modules.
-const EXTERNAL_PACKAGES = [
-  'react',
-  'react-dom',
-  'react/jsx-runtime',
-  'react/jsx-dev-runtime',
-  '@uniweb/core',
-]
+import { externalShimPackages } from './runtime-externals.js'
 
 // Match `./chunk.js` only in actual ESM import positions — `from './x'`,
 // `import './x'`, or `import('./x')`. A broad "match any quoted ./x.js"
@@ -100,6 +84,10 @@ export async function fetchFoundationToCache(url, { onProgress = () => {} } = {}
     const cached = join(cacheDir, name)
     if (existsSync(cached)) {
       onProgress(`using cached foundation: ${cached}`)
+      // Refresh the external shims even on a cache hit: it's a handful of tiny
+      // files, and it self-heals a cache populated by an older unipress (which
+      // left an empty node_modules or dead symlinks that no longer resolve).
+      await writeExternalShims(cacheDir, onProgress)
       return cached
     }
   }
@@ -138,7 +126,7 @@ export async function fetchFoundationToCache(url, { onProgress = () => {} } = {}
       if (!fetched.has(discovered)) queue.push(discovered)
     }
   }
-  await linkExternals(cacheDir, onProgress)
+  await writeExternalShims(cacheDir, onProgress)
   const entryPath = join(cacheDir, entryName)
   onProgress(`foundation cached at ${cacheDir} (${fetched.size} file(s))`)
   return entryPath
@@ -171,63 +159,32 @@ async function pickRemoteEntry(baseUrl, onProgress) {
   )
 }
 
-// Make unipress's own copies of the externalized packages reachable
-// from the cache dir. Node's ESM loader walks up from the importing
-// file looking for `node_modules/<name>` — by placing a node_modules
-// directory next to the cached entry with symlinks to each
-// external's package directory, bare imports inside the foundation
-// resolve to unipress's already-installed copies. This keeps a single
-// React instance (unipress's) across host and foundation.
-async function linkExternals(cacheDir, onProgress) {
+// Lay shim modules for the foundation's externalized peer deps into a
+// node_modules beside the cached entry, so the dynamically imported foundation
+// resolves react / react-dom / @uniweb/core to unipress's own bundled instances
+// (via the globalThis bridge in runtime-externals.js) rather than hunting for a
+// node_modules that isn't there.
+//
+// Replaces the old symlink-to-local-copies approach, which couldn't locate
+// on-disk copies inside the `bun --compile` binary: the deps are bundled into
+// the binary, and require.resolve resolves relative to the CWD, so it found
+// nothing when unipress ran from a project with no react up its tree. The shims
+// read the bridge instead of resolving a real package, so they work from any
+// directory and in any distribution. See runtime-externals.js for the full
+// rationale and the single-instance guarantee.
+//
+// Idempotent and overwriting: cheap (a handful of tiny files), and self-heals a
+// cache left in a bad state by an older unipress.
+async function writeExternalShims(cacheDir, onProgress) {
   const nmDir = join(cacheDir, 'node_modules')
-  await mkdir(nmDir, { recursive: true })
-  // Collapse subpath specifiers (react/jsx-runtime → react) to the
-  // package-root specifier we actually link. Deduped.
-  const rootSpecs = new Set()
-  for (const spec of EXTERNAL_PACKAGES) {
-    rootSpecs.add(spec.startsWith('@')
-      ? spec.split('/').slice(0, 2).join('/')  // '@scope/name'
-      : spec.split('/')[0])                     // 'name'
-  }
-  for (const name of rootSpecs) {
-    const dest = name.startsWith('@')
-      ? join(nmDir, ...name.split('/'))         // node_modules/@scope/name
-      : join(nmDir, name)                       // node_modules/name
-    if (existsSync(dest)) continue
-    try {
-      const pkgDir = findPackageRoot(name)
-      if (!pkgDir) {
-        onProgress(`  warn: cannot find '${name}' in unipress deps — foundation may fail to import`)
-        continue
-      }
-      await mkdir(dirname(dest), { recursive: true })
-      await symlink(pkgDir, dest, 'dir')
-      onProgress(`  linked ${name} → ${pkgDir}`)
-    } catch (err) {
-      onProgress(`  warn: linking ${name} failed: ${err.message}`)
+  for (const pkg of externalShimPackages()) {
+    const pkgDir = join(nmDir, ...pkg.dir.split('/'))
+    await mkdir(pkgDir, { recursive: true })
+    await writeFile(join(pkgDir, 'package.json'), pkg.packageJson)
+    for (const [rel, source] of Object.entries(pkg.files)) {
+      await writeFile(join(pkgDir, rel), source)
     }
-  }
-}
-
-function findPackageRoot(name) {
-  try {
-    // Resolve the package's `package.json` to find its root.
-    const pkgJson = require.resolve(`${name}/package.json`)
-    return dirname(pkgJson)
-  } catch {
-    // Fallback: resolve a default export and strip back.
-    try {
-      const entry = require.resolve(name)
-      let dir = dirname(entry)
-      while (dir !== dirname(dir)) {
-        if (existsSync(join(dir, 'package.json'))) {
-          const pkg = JSON.parse(require('fs').readFileSync(join(dir, 'package.json'), 'utf8'))
-          if (pkg.name === name || pkg.name === name.split('/')[0]) return dir
-        }
-        dir = dirname(dir)
-      }
-    } catch {}
-    return null
+    onProgress(`  shimmed ${pkg.dir} → unipress's bundled copy`)
   }
 }
 

package/src/orchestrator.js

@@ -21,14 +21,23 @@
 //
 // React-instance note (gotcha #2): @uniweb/runtime/ssr (built bundle) imports
 // React as an external; the foundation does the same. Both must resolve to the
-// same React instance, otherwise hooks in foundation components throw "Invalid
-// hook call". Inside this monorepo react is hoisted; in a real npm install of
-// unipress, both also resolve from unipress's node_modules.
+// SAME React instance, otherwise hooks in foundation components throw "Invalid
+// hook call" — and the foundation must see the SAME @uniweb/core unipress built
+// the Website graph with. Importing runtime-externals.js (below) publishes
+// unipress's own bundled react / react-dom / @uniweb/core on a globalThis
+// bridge and drives the cache-side shim modules that the fetched foundation
+// resolves against, guaranteeing one shared instance regardless of how unipress
+// is run (source, npm install, or the bun --compile binary). See
+// runtime-externals.js for the full rationale.
 
 import { pathToFileURL } from 'node:url'
 import { readFile } from 'node:fs/promises'
 import { initPrerender } from '@uniweb/runtime/ssr'
 import { FoundationResolutionError, CompileError } from './errors.js'
+// Side-effect import: sets the globalThis bridges before any foundation is
+// dynamically imported. ESM evaluates it once (foundation-fetch.js imports it
+// too, to generate the matching shims).
+import './runtime-externals.js'
 
 export async function importFoundation(resolvedPath) {
   try {

package/src/runtime-externals.js

@@ -0,0 +1,138 @@
+// Single-instance linkage for dynamically imported foundations.
+//
+// A built foundation externalizes its peer deps — react, react-dom,
+// react-dom/server, react/jsx-runtime, react/jsx-dev-runtime, @uniweb/core
+// (the set in @uniweb/build's foundation/config.js DEFAULT_EXTERNALS). When
+// unipress fetches a foundation to its cache and dynamically imports the built
+// entry.js, those bare imports must resolve to unipress's OWN copies so the
+// foundation shares one React instance with @uniweb/runtime/ssr and one
+// @uniweb/core with the Website graph the orchestrator builds.
+//
+// The old approach symlinked unipress's node_modules copies beside the cached
+// entry. That relies on those copies existing on disk and being locatable via
+// require.resolve — which fails in the `bun --compile` standalone binary: the
+// deps are bundled INTO the binary, and require.resolve does CWD-relative
+// resolution, so it finds nothing when unipress runs from a project (like a
+// loose book folder) that has no react up its directory tree. The symlink step
+// then produced an empty node_modules and the foundation import failed with
+// "Cannot find module 'react/jsx-runtime'".
+//
+// Instead we mirror @uniweb/runtime's worker-isolate shims (its
+// build-worker.js): publish each package on a globalThis bridge here, and write
+// tiny shim modules into the cache's co-located node_modules (see
+// writeExternalShims in foundation-fetch.js) that re-export from the bridge.
+// Bun/Node resolve the foundation's bare imports to the shims (nearest
+// node_modules wins); each shim reads the bridge and yields unipress's exact
+// instance — no on-disk package needed, works identically in the compiled
+// binary and in source/npm mode.
+//
+// Why globalThis rather than a direct import inside the shim: the shim lives on
+// disk beside the foundation; an `import 'react'` from it would re-enter
+// resolution (and in the binary resolve to nothing). Reading a global sidesteps
+// module resolution entirely — the same reason the isolate uses it.
+//
+// Importing this module has the SIDE EFFECT of setting the globalThis bridges,
+// so it must be imported before any foundation is dynamically imported. Both
+// foundation-fetch.js (which writes the shims) and orchestrator.js (which does
+// the import) import it; ESM evaluates it once.
+
+import * as React from 'react'
+import * as ReactJsxRuntime from 'react/jsx-runtime'
+import * as ReactJsxDevRuntime from 'react/jsx-dev-runtime'
+import * as ReactDom from 'react-dom'
+import * as ReactDomServer from 'react-dom/server'
+import * as UniwebCore from '@uniweb/core'
+
+// globalThis bridge keys. Namespaced to unipress so they never collide with
+// @uniweb/runtime's worker isolate (__PLATFORM_*), which a foundation could
+// conceivably bundle into the same realm.
+const REACT_KEY = '__UNIPRESS_REACT'
+const JSX_RUNTIME_KEY = '__UNIPRESS_JSX_RUNTIME'
+const JSX_DEV_RUNTIME_KEY = '__UNIPRESS_JSX_DEV_RUNTIME'
+const REACT_DOM_KEY = '__UNIPRESS_REACT_DOM'
+const REACT_DOM_SERVER_KEY = '__UNIPRESS_REACT_DOM_SERVER'
+const UNIWEB_CORE_KEY = '__UNIPRESS_UNIWEB_CORE'
+
+globalThis[REACT_KEY] = React
+globalThis[JSX_RUNTIME_KEY] = ReactJsxRuntime
+globalThis[JSX_DEV_RUNTIME_KEY] = ReactJsxDevRuntime
+globalThis[REACT_DOM_KEY] = ReactDom
+globalThis[REACT_DOM_SERVER_KEY] = ReactDomServer
+globalThis[UNIWEB_CORE_KEY] = UniwebCore
+
+const VALID_IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/
+
+// Generate an ESM shim module that re-exports every named export of `ns` from
+// the globalThis bridge. Names are enumerated from the live namespace (as
+// build-worker.js does) so the shim tracks the actual React / core surface
+// without a hardcoded list. Non-identifier keys (e.g. "module.exports" from CJS
+// interop) are skipped; `default` is re-exported explicitly.
+function shimSource(globalKey, ns) {
+  const names = Object.keys(ns).filter(
+    (name) => name !== 'default' && VALID_IDENTIFIER.test(name)
+  )
+  return [
+    `// AUTO-GENERATED by unipress — re-exports from globalThis.${globalKey}.`,
+    `// unipress publishes its own bundled instance there (see runtime-externals.js),`,
+    `// giving this dynamically-imported foundation the SAME instance unipress uses.`,
+    `const __ns = globalThis.${globalKey}`,
+    `export default __ns?.default ?? __ns`,
+    ...names.map((name) => `export const ${name} = __ns.${name}`),
+    ''
+  ].join('\n')
+}
+
+function modulePackageJson(name, exportsMap) {
+  return JSON.stringify(
+    {
+      name,
+      type: 'module',
+      exports: { ...exportsMap, './package.json': './package.json' }
+    },
+    null,
+    2
+  )
+}
+
+// The shim packages to lay into a fetched foundation's co-located node_modules.
+// Each entry: the package directory (relative to node_modules, POSIX-style),
+// its package.json text, and the shim files keyed by relative path. Subpath
+// specifiers (react/jsx-runtime, react-dom/server) are served through the
+// package's `exports` map so Node/Bun resolve them to the right shim file.
+export function externalShimPackages() {
+  return [
+    {
+      dir: 'react',
+      packageJson: modulePackageJson('react', {
+        '.': './index.js',
+        './jsx-runtime': './jsx-runtime.js',
+        './jsx-dev-runtime': './jsx-dev-runtime.js'
+      }),
+      files: {
+        'index.js': shimSource(REACT_KEY, React),
+        'jsx-runtime.js': shimSource(JSX_RUNTIME_KEY, ReactJsxRuntime),
+        'jsx-dev-runtime.js': shimSource(JSX_DEV_RUNTIME_KEY, ReactJsxDevRuntime)
+      }
+    },
+    {
+      dir: 'react-dom',
+      packageJson: modulePackageJson('react-dom', {
+        '.': './index.js',
+        './server': './server.js'
+      }),
+      files: {
+        'index.js': shimSource(REACT_DOM_KEY, ReactDom),
+        'server.js': shimSource(REACT_DOM_SERVER_KEY, ReactDomServer)
+      }
+    },
+    {
+      dir: '@uniweb/core',
+      packageJson: modulePackageJson('@uniweb/core', {
+        '.': './index.js'
+      }),
+      files: {
+        'index.js': shimSource(UNIWEB_CORE_KEY, UniwebCore)
+      }
+    }
+  ]
+}