@uniweb/unipress 0.4.18 → 0.4.19

package/README.md

@@ -90,7 +90,7 @@ The first PDF run downloads Typst 0.14.2 to `~/Library/Caches/unipress/typst/0.1
 Any foundation that declares an `outputs: { … }` map on its default export can drive unipress. Point `document.yml`'s `foundation:` at:
 
 - a registry ref: `@<namespace>/<name>@<version>` — fetched from the Uniweb registry, cached locally,
-- a URL: `https://…/foundation.js`,
+- a URL: `https://…/entry.js`,
 - a local filesystem path: `./foundation`, `/abs/path`, etc.
 
 The local-path form is the everyday dev loop — point unipress at a foundation directory you're iterating on, no publish step needed:
@@ -113,7 +113,7 @@ unipress compile <dir> [options]
                       Overrides the format: field in document.yml.
   --foundation <ref>  Override document.yml's foundation. Accepts:
                         - registry ref:  @<namespace>/<name>@<version>
-                        - URL:           https://…/foundation.js
+                        - URL:           https://…/entry.js
                         - path:          ./foundation, /abs/path, …
   --out <path>        Output file (default: ./<dir-basename>.<ext>).
   --config <path>     Explicit config file (default: <dir>/unipress.config.js).

package/docs/troubleshooting.md

@@ -54,7 +54,7 @@ Set `foundation:` in `document.yml`, or pass `--foundation <ref>`. Four ref form
 foundation: "@uniweb/book@0.1.0"
 
 # Or a full URL.
-foundation: "https://example.com/foundations/my-foundation/foundation.js"
+foundation: "https://example.com/foundations/my-foundation/entry.js"
 
 # Or a local filesystem path (relative to document.yml).
 foundation: "./path/to/foundation"
@@ -72,7 +72,7 @@ The package isn't installed anywhere `Node` can see from the content directory.
 
 Inside a pnpm workspace, foundations linked via `pnpm-workspace.yaml` globs resolve automatically.
 
-## `FoundationResolutionError: expected built foundation at <path>/dist/foundation.js`
+## `FoundationResolutionError: expected built foundation at <path>/dist/entry.js`
 
 The foundation package isn't built. From the workspace root:
 
@@ -80,7 +80,7 @@ The foundation package isn't built. From the workspace root:
 pnpm --filter <foundation-name> build
 ```
 
-unipress consumes the built artifact (`dist/foundation.js`), not the source.
+unipress consumes the built artifact (`dist/entry.js`), not the source.
 
 ## `CompileError: foundation does not expose compileDocument`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/unipress",
-  "version": "0.4.18",
+  "version": "0.4.19",
   "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,10 +49,10 @@
     "prompts": "^2.4.2",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
-    "@uniweb/runtime": "0.8.18",
     "@uniweb/build": "0.14.13",
-    "@uniweb/core": "0.7.13",
+    "@uniweb/runtime": "0.8.18",
     "@uniweb/content-reader": "1.1.12",
+    "@uniweb/core": "0.7.13",
     "@uniweb/semantic-parser": "1.1.17"
   },
   "scripts": {

package/src/foundation-fetch.js

@@ -2,23 +2,29 @@
 // full dist tree so Node can import it.
 //
 // Cache layout:
-//   <unipress cache>/foundations/<host>/<pathish>/foundation.js
+//   <unipress cache>/foundations/<host>/<pathish>/entry.js
 //   <unipress cache>/foundations/<host>/<pathish>/<chunk>.js
 //   ... etc
 //
 // where <pathish> is the URL's path with leading slashes stripped and
-// the trailing /foundation.js stripped — the same URL always maps to
+// the trailing entry filename stripped — the same URL always maps to
 // the same cache path.
 //
-// A built foundation is a small entry (`foundation.js`) plus a set of
-// sibling chunks referenced by relative imports (and further chunks
-// dynamically imported from those). `fetchFoundationToCache` walks the
-// import graph: it downloads foundation.js, scans for `./*.js` imports
-// (static and dynamic), fetches each, and recurses. That's enough to
-// cover @uniweb/build's output — all sibling chunks live next to
-// foundation.js. Imports NOT starting with './' are bare specifiers
-// (external like 'react') or absolute URLs and are not part of the
-// fetch graph.
+// A built foundation is a small entry (`entry.js`, the @uniweb/build
+// standard output name) plus a set of sibling chunks referenced by
+// relative imports (and further chunks dynamically imported from those).
+// `fetchFoundationToCache` walks the import graph: it downloads the entry,
+// scans for `./*.js` imports (static and dynamic), fetches each, and
+// recurses. That's enough to cover @uniweb/build's output — all sibling
+// chunks live next to the entry. Imports NOT starting with './' are bare
+// specifiers (external like 'react') or absolute URLs and are not part of
+// the fetch graph.
+//
+// Entry name: the framework standard is `entry.js`. Foundations published
+// before @uniweb/build's entry rename serve `foundation.js`, so the fetch
+// probes `entry.js` first and falls back to `foundation.js` (see
+// ENTRY_CANDIDATES) — both when probing the registry and when reusing a
+// cached download.
 //
 // Integrity: the fetch is unverified today. Once the Uniweb registry
 // publishes integrity data, the catalog entry can carry an `integrity:`
@@ -52,6 +58,13 @@ const EXTERNAL_PACKAGES = [
 // picks up Node-core strings embedded in bundled commonjs shims.
 const RELATIVE_JS_IMPORT = /(?:from\s*|\bimport\s*\(?\s*)['"](\.\/[^'"]+\.(?:js|mjs|cjs))['"]/g
 
+// Foundation entry filename. The framework standard is `entry.js`;
+// `foundation.js` is the legacy name some already-published foundations
+// still serve. Prefer the standard, fall back to the legacy name — both
+// when probing the registry and when reusing a cached download.
+const ENTRY_CANDIDATES = ['entry.js', 'foundation.js']
+const ENTRY_FILENAME_RE = /\/(?:entry|foundation)\.js$/i
+
 export function getFoundationCacheDir(url) {
   let parsed
   try {
@@ -63,33 +76,49 @@ export function getFoundationCacheDir(url) {
     )
   }
   const host = parsed.host.replace(/:/g, '_')
-  let p = parsed.pathname.replace(/^\/+/, '').replace(/\/foundation\.js$/i, '')
+  // Strip a leading slash and any trailing entry filename or slash so the
+  // same foundation maps to one cache dir whether the URL carries entry.js,
+  // foundation.js, or just the containing directory.
+  let p = parsed.pathname.replace(/^\/+/, '').replace(ENTRY_FILENAME_RE, '').replace(/\/$/, '')
   return join(getCacheDir(), 'foundations', host, p)
 }
 
 export function getFoundationCachePath(url) {
-  return join(getFoundationCacheDir(url), 'foundation.js')
+  const dir = getFoundationCacheDir(url)
+  for (const name of ENTRY_CANDIDATES) {
+    const candidate = join(dir, name)
+    if (existsSync(candidate)) return candidate
+  }
+  return join(dir, ENTRY_CANDIDATES[0])
 }
 
 export async function fetchFoundationToCache(url, { onProgress = () => {} } = {}) {
   const cacheDir = getFoundationCacheDir(url)
-  const entryPath = join(cacheDir, 'foundation.js')
-  if (existsSync(entryPath)) {
-    onProgress(`using cached foundation: ${entryPath}`)
-    return entryPath
+
+  // Reuse a prior download under either the standard or legacy entry name.
+  for (const name of ENTRY_CANDIDATES) {
+    const cached = join(cacheDir, name)
+    if (existsSync(cached)) {
+      onProgress(`using cached foundation: ${cached}`)
+      return cached
+    }
   }
   onProgress(`downloading foundation graph from ${url}`)
   await mkdir(cacheDir, { recursive: true })
 
   // Directory URL the individual chunk files live under. Works whether
-  // the input URL ends in /foundation.js or at the containing directory.
+  // the input URL ends in an entry filename or at the containing directory.
   const urlObj = new URL(url)
-  const pathname = urlObj.pathname.replace(/\/foundation\.js$/i, '/')
+  const pathname = urlObj.pathname.replace(ENTRY_FILENAME_RE, '/')
   urlObj.pathname = pathname.endsWith('/') ? pathname : pathname + '/'
   const baseUrl = urlObj.toString()
 
+  // Prefer entry.js (framework standard); fall back to foundation.js
+  // (foundations published before the entry rename).
+  const entryName = await pickRemoteEntry(baseUrl, onProgress)
+
   const fetched = new Set()
-  const queue = ['foundation.js']
+  const queue = [entryName]
   while (queue.length > 0) {
     const rel = queue.shift()
     if (fetched.has(rel)) continue
@@ -110,14 +139,42 @@ export async function fetchFoundationToCache(url, { onProgress = () => {} } = {}
     }
   }
   await linkExternals(cacheDir, onProgress)
+  const entryPath = join(cacheDir, entryName)
   onProgress(`foundation cached at ${cacheDir} (${fetched.size} file(s))`)
   return entryPath
 }
 
+// Probe the registry for the foundation's entry file. Returns the first
+// of ENTRY_CANDIDATES the host serves (prefer `entry.js`, tolerate the
+// legacy `foundation.js`). A plain GET is used rather than HEAD so the
+// check works against any static host; only the status is needed, so the
+// body is cancelled — the graph walk re-fetches the entry.
+async function pickRemoteEntry(baseUrl, onProgress) {
+  for (const name of ENTRY_CANDIDATES) {
+    const probeUrl = new URL(name, baseUrl).toString()
+    let res
+    try {
+      res = await fetch(probeUrl)
+    } catch {
+      continue
+    }
+    res.body?.cancel?.()
+    if (res.ok) return name
+    if (name !== ENTRY_CANDIDATES[ENTRY_CANDIDATES.length - 1]) {
+      onProgress(`  ${name} not found, trying legacy entry name…`)
+    }
+  }
+  throw new FoundationFetchError(
+    `foundation entry not found under ${baseUrl}\n` +
+    `tried: ${ENTRY_CANDIDATES.join(', ')}\n` +
+    `hint: check the foundation is published at that version`
+  )
+}
+
 // 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 foundation.js with symlinks to each
+// 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.

package/src/foundation-loader.js

@@ -7,8 +7,8 @@
 //
 // Five accepted ref forms:
 //
-//   1. URL ............ https://.../foundation.js  — downloaded + cached
-//   2. Local path ..... ./foo, ../foo, /abs/foo, ./foo/dist/foundation.js
+//   1. URL ............ https://.../entry.js  — downloaded + cached
+//   2. Local path ..... ./foo, ../foo, /abs/foo, ./foo/dist/entry.js
 //   3. Registry ref ... @<namespace>/<name>@<version> — constructed into a
 //                       URL via the registry base (UNIWEB_REGISTRY_URL or
 //                       the production default), then resolved as URL
@@ -24,7 +24,7 @@
 //
 // The chosen entry for a package is its `exports['./dist']` map, NOT the
 // default `.` entry — the default points at source (_entry.generated.js)
-// and is only valid inside a Vite build. `dist/foundation.js` is the
+// and is only valid inside a Vite build. `dist/entry.js` is the
 // built artifact (the federated module) that Node can import.
 
 import { existsSync, statSync, readFileSync } from 'node:fs'
@@ -45,14 +45,14 @@ const REGISTRY_REF_PATTERN = /^@([a-z0-9][a-z0-9._-]*)\/([a-z0-9][a-z0-9._-]*)@(
 // unipress's bundled foundations are distributed as static artifacts on
 // the unipress repo's GitHub Pages site. URL pattern:
 //
-//   https://uniweb.github.io/unipress/foundations/<name>/<version>/foundation.js
+//   https://uniweb.github.io/unipress/foundations/<name>/<version>/entry.js
 //
 // The namespace portion of a registry ref is implicit — every foundation
 // served from this base is under @uniweb/. Set UNIWEB_REGISTRY_URL to
 // override (e.g., for testing against a local http.server during foundation
 // development, or for users with a private alternative).
 const DEFAULT_REGISTRY_BASE = 'https://uniweb.github.io/unipress'
-const DEFAULT_BUILT_ENTRY = 'dist/foundation.js'
+const DEFAULT_BUILT_ENTRY = 'dist/entry.js'
 
 function getRegistryBase() {
   const raw = process.env.UNIWEB_REGISTRY_URL || DEFAULT_REGISTRY_BASE
@@ -67,7 +67,7 @@ function getRegistryBase() {
 // `UNIWEB_REGISTRY_URL=https://my.host/by-ns/uniweb` and live without the
 // per-namespace split, or maintain a redirect rule on that host).
 function buildRegistryUrl(namespace, name, version) {
-  return `${getRegistryBase()}/foundations/${name}/${version}/foundation.js`
+  return `${getRegistryBase()}/foundations/${name}/${version}/entry.js`
 }
 
 export async function resolveFoundationRef(ref, { anchorDir, onProgress = () => {} } = {}) {
@@ -188,7 +188,7 @@ async function resolvePackageRef(name, anchorDir) {
     : null
 
   // Prefer the explicit `./dist` exports subpath if declared; otherwise
-  // fall back to the convention `dist/foundation.js`.
+  // fall back to the convention `dist/entry.js`.
   const distExport = pickBuiltEntry(pkg?.exports)
   const file = distExport
     ? resolve(pkgRoot, distExport)
@@ -218,7 +218,7 @@ function findPackageDir(name, fromDir) {
   }
 }
 
-// A foundation's `exports['./dist']` entry points at the built `foundation.js`.
+// A foundation's `exports['./dist']` entry points at the built `entry.js`.
 // The value can be a string or a conditional-exports object; we accept both.
 function pickBuiltEntry(exports) {
   if (!exports || typeof exports !== 'object') return null

package/src/foundations-data.js

@@ -16,7 +16,7 @@
  * Foundations are deployed as static artifacts to the unipress repo's
  * GitHub Pages site. URL pattern:
  *
- *   https://uniweb.github.io/unipress/foundations/<name>/<version>/foundation.js
+ *   https://uniweb.github.io/unipress/foundations/<name>/<version>/entry.js
  *
  * On every push to main, `.github/workflows/deploy-foundations.yml`
  * builds each `foundations/<name>/` and layers the resulting `dist/` into
@@ -68,7 +68,7 @@
 const PUBLIC_FOUNDATIONS_BASE = 'https://uniweb.github.io/unipress/foundations'
 
 function publicUrl(name, version) {
-  return `${PUBLIC_FOUNDATIONS_BASE}/${name}/${version}/foundation.js`
+  return `${PUBLIC_FOUNDATIONS_BASE}/${name}/${version}/entry.js`
 }
 
 const BOOK_FOUNDATION = {

package/src/orchestrator.js

@@ -37,7 +37,7 @@ export async function importFoundation(resolvedPath) {
     throw new FoundationResolutionError(
       `failed to import foundation at ${resolvedPath}\n` +
       `cause: ${err.message}\n` +
-      `hint: confirm the foundation was built with @uniweb/build (dist/foundation.js)`
+      `hint: confirm the foundation was built with @uniweb/build (dist/entry.js)`
     )
   }
 }