@uniweb/build 0.10.3 → 0.11.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.10.3",
+  "version": "0.11.3",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -57,8 +57,8 @@
     "@uniweb/theming": "0.1.3"
   },
   "optionalDependencies": {
-    "@uniweb/runtime": "0.8.3",
-    "@uniweb/content-reader": "1.1.4",
+    "@uniweb/runtime": "0.8.5",
+    "@uniweb/content-reader": "1.1.6",
     "@uniweb/schemas": "0.2.1"
   },
   "peerDependencies": {
@@ -68,7 +68,7 @@
     "@tailwindcss/vite": "^4.0.0",
     "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
     "vite-plugin-svgr": "^4.0.0",
-    "@uniweb/core": "0.7.2"
+    "@uniweb/core": "0.7.4"
   },
   "peerDependenciesMeta": {
     "vite": {

package/src/content/index.js

@@ -1,13 +1,32 @@
 /**
  * Clean Content Entry Point
  *
- * Exposes only collectSiteContent and its clean dependency chain
- * (Node builtins, js-yaml, @uniweb/theming). No Vite, sharp, or React.
- *
- * Used by Studio's sidecar (Bun-compiled binary) where those heavy
- * peer/native dependencies aren't available.
+ * Exposes content-collection helpers and their clean dependency chain
+ * (Node builtins, js-yaml, @uniweb/theming, @uniweb/core). No Vite,
+ * sharp, or React. Used by Studio's sidecar (Bun-compiled binary) and
+ * by @uniweb/unipress (CLI compile path) where those heavy peer/native
+ * dependencies aren't available.
  *
  * @module @uniweb/build/content
  */
 
 export { collectSiteContent } from '../site/content-collector.js'
+
+// Collections + fetch resolution. Pure functions on the clean dep
+// chain — re-exported here so headless callers (unipress, sidecars)
+// can resolve `collections:` declarations without importing
+// `@uniweb/build/site` (which pulls Vite via its plugin index).
+export {
+  processCollections,
+  writeCollectionFiles,
+  getCollectionLastModified,
+} from '../site/collection-processor.js'
+export {
+  parseFetchConfig,
+  executeFetch,
+  applyFilter,
+  applySort,
+  applyPostProcessing,
+  mergeDataIntoContent,
+  singularize,
+} from '../site/data-fetcher.js'

package/src/foundation/config.js

@@ -37,6 +37,7 @@ import { foundationPlugin } from '../vite-foundation-plugin.js'
 const DEFAULT_EXTERNALS = [
   'react',
   'react-dom',
+  'react-dom/server',
   'react/jsx-runtime',
   'react/jsx-dev-runtime',
   '@uniweb/core'

package/src/generate-entry.js

@@ -25,6 +25,53 @@ import { join, dirname } from 'node:path'
 import { discoverComponents, discoverLayoutsInPath } from './schema.js'
 import { extractAllRuntimeSchemas, extractAllLayoutRuntimeSchemas } from './runtime-schema.js'
 
+/**
+ * Packages that may be bundled inside a foundation but require single-instance
+ * access from a host environment (currently: unipress). When a foundation
+ * declares any of these as a dependency, we re-export the named symbols
+ * from the generated entry so the host can reach the foundation's bundled
+ * copy instead of importing its own — avoiding the dual-instance trap
+ * (each side gets its own React.createContext, registrations land in a
+ * context the other side can't see).
+ *
+ * Detection is by `dependencies` / `peerDependencies` declaration. Vite
+ * would fail to resolve an undeclared bare import anyway, so "declared"
+ * and "imported" stay aligned in practice. A foundation that declares one
+ * of these and never actually imports it pays the cost of bundling it (the
+ * re-export keeps the symbols alive) — minor and easily fixed by removing
+ * the unused dep.
+ *
+ * The export list is a public-API contract: removing a symbol here breaks
+ * hosts compiled against older built foundations that re-exported it. Add
+ * conservatively.
+ */
+const HOST_SHAREABLE_PACKAGES = {
+  '@uniweb/press': ['compileSubtree', 'compileDocument']
+}
+
+/**
+ * Detect which HOST_SHAREABLE_PACKAGES the foundation declares as a dep.
+ * Reads the foundation's own package.json (one level above srcDir).
+ * Returns [] if package.json is missing or unreadable.
+ */
+async function detectHostShareableImports(srcDir) {
+  const packages = Object.keys(HOST_SHAREABLE_PACKAGES)
+  if (packages.length === 0) return []
+
+  const pkgPath = join(dirname(srcDir), 'package.json')
+  if (!existsSync(pkgPath)) return []
+
+  let pkg
+  try {
+    pkg = JSON.parse(await readFile(pkgPath, 'utf-8'))
+  } catch {
+    return []
+  }
+
+  const declared = { ...pkg.dependencies, ...pkg.peerDependencies }
+  return packages.filter(p => p in declared)
+}
+
 /**
  * Detect foundation config file (for props, vars, etc.)
  *
@@ -79,6 +126,7 @@ function generateEntrySource(components, options = {}) {
     meta = {},
     layouts = {},
     layoutMeta = {},
+    hostShareableImports = [],
   } = options
 
   const componentNames = Object.keys(components).sort()
@@ -148,6 +196,18 @@ function generateEntrySource(components, options = {}) {
   // Default export — non-component data (naturally unforgeable key)
   lines.push('')
   lines.push('export default { meta, capabilities, layoutMeta }')
+
+  // Re-export host-shareable packages the foundation actually imports.
+  // Lets unipress reach the foundation's bundled copy instead of importing
+  // its own (which would create a dual-instance React-context trap).
+  if (hostShareableImports.length > 0) {
+    lines.push('')
+    for (const pkg of hostShareableImports) {
+      const symbols = HOST_SHAREABLE_PACKAGES[pkg]
+      lines.push(`export { ${symbols.join(', ')} } from '${pkg}'`)
+    }
+  }
+
   lines.push('')
 
   return lines.join('\n')
@@ -239,6 +299,9 @@ export async function generateEntryPoint(srcDir, outputPath = null, options = {}
   // Extract per-layout runtime metadata from meta.js files
   const layoutMeta = extractAllLayoutRuntimeSchemas(layouts)
 
+  // Detect which host-shareable packages the foundation imports
+  const hostShareableImports = await detectHostShareableImports(srcDir)
+
   // Generate source
   const source = generateEntrySource(components, {
     cssPath,
@@ -246,6 +309,7 @@ export async function generateEntryPoint(srcDir, outputPath = null, options = {}
     meta,
     layouts,
     layoutMeta,
+    hostShareableImports,
   })
 
   // Write to file (skip if content unchanged to avoid unnecessary watcher triggers)
@@ -272,6 +336,9 @@ export async function generateEntryPoint(srcDir, outputPath = null, options = {}
   if (foundationExports) {
     console.log(`  - Foundation exports found: ${foundationExports.path}`)
   }
+  if (hostShareableImports.length > 0) {
+    console.log(`  - Host-shareable re-exports: ${hostShareableImports.join(', ')}`)
+  }
 
   return {
     outputPath: output,
@@ -280,6 +347,7 @@ export async function generateEntryPoint(srcDir, outputPath = null, options = {}
     foundationExports,
     meta,
     layoutMeta,
+    hostShareableImports,
   }
 }
 

package/src/import-map-plugin.js

@@ -20,6 +20,7 @@
 const DEFAULT_EXTERNALS = [
   'react',
   'react-dom',
+  'react-dom/server',
   'react/jsx-runtime',
   'react/jsx-dev-runtime',
   '@uniweb/core',

package/src/prerender.js

@@ -434,6 +434,29 @@ export async function prerenderSite(siteDir, options = {}) {
   }
   const defaultSiteContent = JSON.parse(await readFile(contentPath, 'utf8'))
 
+  // Link-mode detection: if site.yml's foundation is a registry scoped ref
+  // or a URL, the foundation lives on the hosting edge, not on disk. Static
+  // prerender (which writes dist/<route>/index.html) has no local JS to
+  // execute, so we skip cleanly here. This is the right call for CLI deploy
+  // (where the Worker SSRs from R2 at serve time) and for any site whose
+  // foundation is deliberately remote. Sites that still need prerender +
+  // registry foundation would need a fetch-and-execute path, tracked as
+  // future work.
+  const fndRef = defaultSiteContent?.config?.foundation
+  const isLinkModeFoundation = (
+    (typeof fndRef === 'string' && (
+      /^@[a-z0-9_-]+\/[a-z0-9_-]+@.+$/.test(fndRef) ||
+      fndRef.startsWith('http://') ||
+      fndRef.startsWith('https://')
+    )) ||
+    (fndRef && typeof fndRef === 'object' && fndRef.url)
+  )
+  if (isLinkModeFoundation) {
+    onProgress(`Link-mode foundation (${typeof fndRef === 'string' ? fndRef : fndRef.url || fndRef.name}) — skipping prerender.`)
+    onProgress('(HTML will be rendered by the serving worker / runtime.)')
+    return { pages: 0, files: [] }
+  }
+
   // Discover all locale content files
   const localeConfigs = await discoverLocaleContents(distDir, defaultSiteContent)
   if (localeConfigs.length > 1) {

package/src/site/assets.js

@@ -322,6 +322,68 @@ export function collectSectionAssets(section, markdownPath, siteRoot) {
   return { assets, hasExplicitPoster, hasExplicitPreview }
 }
 
+/**
+ * Walk the top-level config object (site.yml / document.yml) for asset
+ * references and resolve each into a manifest entry. Catches things like
+ * book.covers.front, banner images, logos in metadata blocks — anything
+ * declared in the config that points at a local file by path.
+ *
+ * Result is keyed by the original source string (the value as it appears
+ * in the config). Foundations look up `website.assets[src]` at compile
+ * time and resolve `entry.resolved` to a filesystem path or `entry.url`
+ * to a URL, depending on the runtime context. This keeps foundations
+ * environment-agnostic — they don't need to know whether the compile
+ * pipeline runs in Node (unipress) or in the browser (editor).
+ *
+ * `walkDataAssets` already filters via `isLocalAssetPath` to skip
+ * non-asset strings (titles, descriptions, etc.).
+ *
+ * @param {Object} siteConfig - Parsed top-level config
+ * @param {string} siteRoot - Site/document root directory
+ * @returns {Object} Asset manifest keyed by original src string
+ */
+export function collectConfigAssets(siteConfig, siteRoot) {
+  const assets = {}
+  if (!siteConfig || typeof siteConfig !== 'object') return assets
+
+  // Anchor for relative-path resolution — `dirname(anchor)` must equal siteRoot
+  // so `assets/front.png` resolves to `<siteRoot>/assets/front.png`.
+  const anchor = `${siteRoot}/_config_anchor`
+
+  // Walk siteConfig with a more permissive filter than `isLocalAssetPath`:
+  // config asset paths often appear without a `./` prefix (e.g.
+  // `book.covers.front: assets/front.png`), which is the natural spelling
+  // for authors. Accept any string with a media extension that isn't an
+  // external URL.
+  const visit = (data) => {
+    if (typeof data === 'string') {
+      if (isExternalUrl(data)) return
+      if (!(isImagePath(data) || isVideoPath(data) || isPdfPath(data))) return
+      const result = resolveAssetPath(data, anchor, siteRoot)
+      if (!result.external && result.resolved) {
+        assets[data] = {
+          original: data,
+          resolved: result.resolved,
+          isImage: result.isImage,
+          isVideo: result.isVideo,
+          isPdf: result.isPdf
+        }
+      }
+      return
+    }
+    if (Array.isArray(data)) {
+      data.forEach(visit)
+      return
+    }
+    if (data && typeof data === 'object') {
+      Object.values(data).forEach(visit)
+    }
+  }
+
+  visit(siteConfig)
+  return assets
+}
+
 /**
  * Merge multiple asset collection results
  *

package/src/site/config.js

@@ -88,6 +88,24 @@ function detectFoundationType(foundation, siteRoot) {
     }
   }
 
+  // Registry scoped ref: "@namespace/name@version". By definition link-mode —
+  // the foundation lives on the hosting edge (R2) and is loaded at runtime.
+  // Surfacing this as `type: 'url'` makes Vite skip the local-foundation
+  // bundling path and use the noop virtual module (no need for VITE_FOUNDATION_MODE=runtime
+  // env var or a local foundation folder). Base URL defaults to the production
+  // worker but is overridable via UNIWEB_REGISTRY_URL for self-hosted / staging
+  // environments.
+  const scopedMatch = /^@([a-z0-9_-]+)\/([a-z0-9_-]+)@(.+)$/.exec(name)
+  if (scopedMatch) {
+    const [, ns, fn, ver] = scopedMatch
+    const base = process.env.UNIWEB_REGISTRY_URL || 'https://site-router.uniweb-edge.workers.dev'
+    return {
+      type: 'url',
+      url: `${base}/foundations/${ns}/${fn}/${ver}/foundation.js`,
+      cssUrl: `${base}/foundations/${ns}/${fn}/${ver}/assets/foundation.css`
+    }
+  }
+
   // Check if it's a local workspace sibling (directory name matches package name)
   const localPath = resolve(siteRoot, '..', name)
   if (existsSync(localPath)) {
@@ -456,7 +474,7 @@ export async function defineSiteConfig(options = {}) {
       // Deduplicate React packages to prevent dual-instance issues
       // Foundation externalizes React; when site bundles it, CJS and ESM
       // copies can coexist without this, causing "useRef of null" errors
-      dedupe: ['react', 'react-dom', 'react/jsx-runtime', 'react/jsx-dev-runtime'],
+      dedupe: ['react', 'react-dom', 'react-dom/server', 'react/jsx-runtime', 'react/jsx-dev-runtime'],
       alias: {
         ...alias,
         ...resolveOverrides?.alias
@@ -491,7 +509,7 @@ export async function defineSiteConfig(options = {}) {
     },
 
     optimizeDeps: {
-      include: ['react', 'react-dom', 'react-dom/client', 'react-router-dom'],
+      include: ['react', 'react-dom', 'react-dom/client', 'react-dom/server', 'react-router-dom'],
       exclude: ['#foundation']
     },
 

package/src/site/content-collector.js

@@ -27,7 +27,7 @@ import { readFile, readdir, stat } from 'node:fs/promises'
 import { join, parse, resolve, sep } from 'node:path'
 import { existsSync, statSync, realpathSync } from 'node:fs'
 import yaml from 'js-yaml'
-import { collectSectionAssets, mergeAssetCollections } from './assets.js'
+import { collectSectionAssets, mergeAssetCollections, collectConfigAssets } from './assets.js'
 import { collectSectionIcons, mergeIconCollections, buildIconManifest } from './icons.js'
 import { parseFetchConfig, singularize } from './data-fetcher.js'
 import { buildTheme, extractFoundationVars } from '../theme/index.js'
@@ -181,13 +181,19 @@ async function readYamlFile(filePath) {
 /**
  * Extract inset references from a ProseMirror document.
  *
- * Walks top-level nodes for `inset_ref` (produced by content-reader
- * for `![alt](@ComponentName){params}` syntax). Each ref is removed from the
- * document and replaced with an `inset_placeholder` node carrying a
- * unique refId. The extracted refs are returned as an array.
+ * Walks the document recursively for `inset_ref` nodes (produced by
+ * content-reader for the `![alt](@ComponentName){params}` /
+ * `[text](@ComponentName){params}` / `[@key]{params}` forms). Each ref
+ * is removed and replaced in-place with an `inset_placeholder` node
+ * carrying a unique refId. The extracted refs are returned as an array.
+ *
+ * Inline insets (mid-paragraph) are kept as inline placeholders so the
+ * paragraph's text flow is preserved; block-level insets (own line)
+ * stay at the document root. Both share the same refId/getInset(refId)
+ * lookup machinery — only the position differs.
  *
  * @param {Object} doc - ProseMirror document (mutated in place)
- * @returns {Array} Array of { refId, type, params, description }
+ * @returns {Array} Array of { refId, type, params, description, embedKind }
  */
 function extractInsets(doc) {
   if (!doc?.content || !Array.isArray(doc.content)) return []
@@ -195,25 +201,34 @@ function extractInsets(doc) {
   const insets = []
   let refIndex = 0
 
-  for (let i = 0; i < doc.content.length; i++) {
-    const node = doc.content[i]
-    if (node.type === 'inset_ref') {
-      const { component, alt, ...params } = node.attrs || {}
-      const refId = `inset_${refIndex++}`
-      insets.push({
-        refId,
-        type: component,
-        params: Object.keys(params).length > 0 ? params : {},
-        title: alt || null,
-      })
-      // Replace in-place with placeholder
-      doc.content[i] = {
-        type: 'inset_placeholder',
-        attrs: { refId },
+  function visit(nodes) {
+    if (!Array.isArray(nodes)) return
+    for (let i = 0; i < nodes.length; i++) {
+      const node = nodes[i]
+      if (!node) continue
+      if (node.type === 'inset_ref') {
+        const { component, alt, embedKind, ...params } = node.attrs || {}
+        const refId = `inset_${refIndex++}`
+        insets.push({
+          refId,
+          type: component,
+          embedKind: embedKind || 'visual',
+          params: Object.keys(params).length > 0 ? params : {},
+          title: alt || null,
+        })
+        nodes[i] = {
+          type: 'inset_placeholder',
+          attrs: { refId, embedKind: embedKind || 'visual' },
+        }
+        continue
+      }
+      if (Array.isArray(node.content)) {
+        visit(node.content)
       }
     }
   }
 
+  visit(doc.content)
   return insets
 }
 
@@ -256,6 +271,33 @@ function isIgnoredFolder(name) {
   return name.startsWith('_')
 }
 
+/**
+ * Workspace-root content profiles, dispatched on the top-level config filename.
+ *
+ * - `site.yml` → site profile: content under `pages/`, page mode (multiple
+ *   sections per page) by default, ordering field is `pages:`. The historical
+ *   default; used for websites.
+ * - `document.yml` → document profile: content under `content/`, folder mode
+ *   (each .md file is its own page/chapter) by default, ordering field is
+ *   `content:` (with `pages:` accepted as a fallback alias). Used by document
+ *   tools like unipress where the natural noun is "content" / "chapter."
+ *
+ * Per-folder folder.yml/page.yml overrides keep working in both profiles —
+ * the profile sets workspace-root defaults; per-folder configs take precedence.
+ * An explicit `paths: { pages: ... }` in either config also overrides the
+ * default content directory.
+ *
+ * Internal mode values match readFolderConfig: 'pages' (folder mode), 'sections' (page mode).
+ */
+const CONTENT_PROFILES = {
+  'site.yml':     { contentDir: 'pages',   defaultMode: 'sections', orderField: 'pages' },
+  'document.yml': { contentDir: 'content', defaultMode: 'pages',    orderField: 'content' }
+}
+
+function getContentProfile(configFile) {
+  return CONTENT_PROFILES[configFile] || CONTENT_PROFILES['site.yml']
+}
+
 /**
  * Read folder configuration, determining content mode from config file presence.
  *
@@ -1926,18 +1968,34 @@ async function collectLayouts(layoutDir, siteRoot, layoutNames = new Set()) {
  * @param {string} sitePath - Path to site directory
  * @param {Object} options - Collection options
  * @param {string} options.foundationPath - Path to foundation directory (for theme vars)
+ * @param {string} [options.configFile='site.yml'] - Name of the top-level config file inside sitePath. Defaults to 'site.yml'. Document tools (unipress) pass 'document.yml'.
  * @returns {Promise<Object>} Site content object with assets manifest
  */
 export async function collectSiteContent(sitePath, options = {}) {
-  const { foundationPath } = options
+  const { foundationPath, configFile = 'site.yml' } = options
 
   // Read site config and raw theme config
-  const siteConfig = await readYamlFile(join(sitePath, 'site.yml'))
-
-  // Resolve content paths from site.yml paths: group, defaulting to standard locations
-  const pagesPath = siteConfig.paths?.pages
-    ? resolve(sitePath, siteConfig.paths.pages)
-    : join(sitePath, 'pages')
+  const siteConfig = await readYamlFile(join(sitePath, configFile))
+
+  // Profile selects workspace-root defaults: site.yml → pages/ + page mode +
+  // pages: ordering; document.yml → content/ + folder mode + content: ordering.
+  const profile = getContentProfile(configFile)
+
+  // Resolve content paths from <config>.paths: group, defaulting per profile.
+  // Backward compatibility: when the document profile's `content/` is missing
+  // but a `pages/` directory exists, fall back to `pages/` so existing unipress
+  // projects (and any document.yml-using setup that predates the profile)
+  // keep working without edits.
+  let pagesPath
+  if (siteConfig.paths?.pages) {
+    pagesPath = resolve(sitePath, siteConfig.paths.pages)
+  } else {
+    const profileDefault = join(sitePath, profile.contentDir)
+    const legacyFallback = join(sitePath, 'pages')
+    pagesPath = (profile.contentDir !== 'pages' && !existsSync(profileDefault) && existsSync(legacyFallback))
+      ? legacyFallback
+      : profileDefault
+  }
 
   const mounts = resolveMounts(siteConfig.paths, sitePath, pagesPath)
 
@@ -1968,14 +2026,21 @@ export async function collectSiteContent(sitePath, options = {}) {
     }
   }
 
-  // Extract page ordering config from site.yml
+  // Extract page ordering config from the top-level config.
+  // Document profile reads the `content:` field (with `pages:` as a back-compat
+  // alias); site profile reads `pages:`. Either way the internal field name is
+  // `pages` so collectPagesRecursive doesn't need to care about profile.
   const siteOrderConfig = {
-    pages: siteConfig.pages,
+    pages: profile.orderField === 'pages'
+      ? siteConfig.pages
+      : (siteConfig[profile.orderField] ?? siteConfig.pages),
     index: siteConfig.index
   }
 
-  // Determine root content mode from folder.yml/page.yml presence in pages directory
-  const { mode: rootContentMode } = await readFolderConfig(pagesPath, 'sections')
+  // Root content mode default comes from the profile (folder mode for
+  // documents, page mode for sites). A folder.yml/page.yml in the pages root
+  // overrides the profile default per readFolderConfig.
+  const { mode: rootContentMode } = await readFolderConfig(pagesPath, profile.defaultMode)
 
   // Collect layout areas from layout/ directory (including named layout subdirectories)
   const { layouts } = await collectLayouts(layoutPath, sitePath, layoutNames)
@@ -1985,9 +2050,18 @@ export async function collectSiteContent(sitePath, options = {}) {
     : siteConfig.layout?.name || null
 
   // Recursively collect all pages
-  const { pages, assetCollection, iconCollection, notFound, versionedScopes } =
+  let { pages, assetCollection, iconCollection, notFound, versionedScopes } =
     await collectPagesRecursive(pagesPath, '/', sitePath, siteOrderConfig, null, null, rootContentMode, mounts, siteLayoutName)
 
+  // Merge top-level config assets (e.g. document.yml's book.covers.front,
+  // banner images, logos) into the manifest. The compile pipeline reads
+  // website.assets[<original src>] to resolve these to filesystem paths
+  // (Node) or URLs (browser) without doing its own I/O.
+  const configAssets = collectConfigAssets(siteConfig, sitePath)
+  if (Object.keys(configAssets).length > 0) {
+    assetCollection = mergeAssetCollections(assetCollection, { assets: configAssets })
+  }
+
   // Deduplicate: at the root level, homepage promotion can create a route
   // collision between the promoted page and a content-less container.
   // At deeper levels, 1:1 mapping means collisions shouldn't happen — warn.

package/src/vite-foundation-plugin.js

@@ -221,6 +221,16 @@ export function foundationBuildPlugin(options = {}) {
       // Build self-contained SSR bundle for edge rendering (Dynamic Workers)
       await buildSSRBundle(outDir)
     },
+
+    async closeBundle() {
+      // esbuild spawns a long-lived service child process on first build() and
+      // keeps it running. Its stop() is the documented teardown for hosts that
+      // need to exit cleanly. Best-effort — never fail the build over this.
+      try {
+        const { stop } = await import('esbuild')
+        await stop?.()
+      } catch {}
+    },
   }
 }