@uniweb/build 1.0.1 → 1.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "1.0.1",
+  "version": "1.1.1",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -23,7 +23,6 @@
     "./import-map-plugin": "./src/import-map-plugin.js",
     "./emit-surface": "./src/uwx/emit-surface.json"
   },
-  "bin": {},
   "files": [
     "src"
   ],
@@ -46,7 +45,7 @@
     "url": "https://github.com/uniweb/build/issues"
   },
   "engines": {
-    "node": ">=20.19"
+    "node": ">=22.12"
   },
   "devDependencies": {
     "vitest": "^4.1.7"
@@ -57,15 +56,15 @@
     "js-yaml": "^4.1.0",
     "sharp": "^0.35.3",
     "yaml": "^2.5.0",
-    "@uniweb/content-reader": "~1.2.8",
+    "@uniweb/projections": "~1.1.0",
     "@uniweb/content-writer": "~1.0.1",
     "@uniweb/semantic-parser": "~1.5.1",
-    "@uniweb/theming": "~1.0.1",
-    "@uniweb/projections": "~1.0.1",
-    "@uniweb/schemas": "~1.0.1"
+    "@uniweb/schemas": "~1.0.1",
+    "@uniweb/content-reader": "~1.2.8",
+    "@uniweb/theming": "~1.1.0"
   },
   "optionalDependencies": {
-    "@uniweb/runtime": "~1.0.1"
+    "@uniweb/runtime": "~1.1.0"
   },
   "peerDependencies": {
     "vite": "^5.0.0 || ^6.0.0 || ^7.0.0",
@@ -74,8 +73,8 @@
     "@tailwindcss/vite": "^4.0.0",
     "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
     "vite-plugin-svgr": "^4.0.0",
-    "@uniweb/runtime": "~1.0.1",
-    "@uniweb/core": "~1.0.1"
+    "@uniweb/core": "~1.1.0",
+    "@uniweb/runtime": "~1.1.0"
   },
   "peerDependenciesMeta": {
     "vite": {

package/src/hosts/ci-workflow.js

@@ -41,7 +41,7 @@ const FALLBACK_PNPM_VERSION = '11'
 
 export function setupSteps({
   packageManager = 'pnpm',
-  nodeVersion = '20',
+  nodeVersion = '22',
   pnpmVersion = FALLBACK_PNPM_VERSION,
   checkout = true,
 } = {}) {

package/src/hosts/cloudflare-pages.js

@@ -207,7 +207,7 @@ async function deploy({ distDir, deployConfig = {}, env = process.env, log = ()
 async function initCi({
   site,
   packageManager = 'pnpm',
-  nodeVersion = '20',
+  nodeVersion = '22',
   pnpmVersion,
   domain = null,
   projectName = null,

package/src/hosts/github-pages.js

@@ -286,7 +286,7 @@ const adapter = {
     foundations = [],
     target = 'site',
     packageManager = 'pnpm',
-    nodeVersion = '20',
+    nodeVersion = '22',
     pnpmVersion,
     domain = null,
   }) {

package/src/hosts/netlify.js

@@ -139,7 +139,7 @@ async function deploy({ distDir, deployConfig = {}, env = process.env, log = ()
 async function initCi({
   site,
   packageManager = 'pnpm',
-  nodeVersion = '20',
+  nodeVersion = '22',
   pnpmVersion,
   domain = null,
   previews = true,

package/src/hosts/vercel.js

@@ -121,7 +121,7 @@ async function deploy({ distDir, deployConfig = {}, env = process.env, log = ()
 async function initCi({
   site,
   packageManager = 'pnpm',
-  nodeVersion = '20',
+  nodeVersion = '22',
   pnpmVersion,
   domain = null,
   previews = true,

package/src/index.js

@@ -73,6 +73,13 @@ export {
   isExtensionUrl,
   isSiteRelativeExtensionUrl
 } from './uwx/site.js'
+// Where a site finds a workspace extension — one rule, which the build, prerender
+// and the dev server follow, for the CLI to ask rather than restate.
+export {
+  extensionCandidates,
+  extensionNameOf,
+  findSiteExtension
+} from './site/workspace-extension.js'
 
 // Foundation source root resolution (reads package.json::main)
 export { resolveFoundationSrcDir, resolveFoundationSrcPath } from './utils/foundation-source-root.js'

package/src/prerender.js

@@ -54,13 +54,20 @@ import { isSiteRelative, resolveExtensionDist } from './site/emit-extensions.js'
  * sections belonged until the page ran in the browser.
  *
  * Resolution order:
- * 1. The extension's own build — `<project>/<name>/dist/` or
- *    `<project>/extensions/<name>/dist/` — found by the emitter's lookup
- *    (`resolveExtensionDist`), so the two lanes find the same build.
+ * 1. The extension's own build — the `dist/` of the workspace extension with the
+ *    URL's name, `<name>/` or `extensions/<name>/` in the folder the site is in or
+ *    a folder above it, up to the workspace root (site/workspace-extension.js) —
+ *    found by the emitter's lookup (`resolveExtensionDist`), so the two lanes find
+ *    the same build.
  * 2. A file in the site's dist, for an extension no workspace package builds (a
  *    pre-built module placed in `public/`). Its bare imports resolve only where
  *    the site's own dependencies carry them.
  * 3. Original URL (absolute or remote — let import() handle it)
+ *
+ * @param {string} url - as the payload carries it
+ * @param {string} distDir - the site's `dist/`
+ * @param {string} projectRoot - the folder the site is in, where the search starts
+ * @param {string} [base] - the site's deployment base
  */
 export function resolveExtensionPath(url, distDir, projectRoot, base) {
   // The payload now carries FINAL, base-resolved URLs (see

package/src/site/config.js

@@ -421,7 +421,11 @@ export async function defineSiteConfig(options = {}) {
       // nothing else resolves them: the foundation dev plugin rewrites a LOCAL
       // foundation's imports, and a served one is not ours to rewrite. So the dev server
       // answers the import map a build writes, bridging to the site's own copies.
-      serveInDev: foundationInfo.type === 'url'
+      // ⭐ An extension is always loaded from a URL — a workspace one, served by the
+      // site plugin from its build, as much as a remote one — so a site with any
+      // extension gets the same bridge. ⛔ Until 2026-10-13 only a URL foundation did,
+      // and in dev an extension's `import 'react'` had nothing to resolve against.
+      serveInDev: foundationInfo.type === 'url' || hasExtensions
     }))
   }
 

package/src/site/emit-extensions.js

@@ -44,10 +44,17 @@
  * the extension from its own build (`resolveExtensionPath`), because the copy
  * sits under the site package, where the extension's bare imports
  * (`@uniweb/core`, `react`) do not resolve.
+ *
+ * ── Which folder is the extension ──
+ *
+ * Not decided here: `./workspace-extension.js` holds the rule, and the dev
+ * server, prerender and the CLI ask it too.
  */
 
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
 import { join, relative, resolve } from 'node:path'
+import { extensionNameOf, findExtensionPackage } from './workspace-extension.js'
+import { stripBasePath } from './extension-urls.js'
 
 /** True for the `/effects/entry.js` form — the only one this site can serve. */
 export function isSiteRelative(decl) {
@@ -64,8 +71,8 @@ function walk(dir, base = dir) {
   })
 }
 
-/** Is this file part of what a browser fetches? */
-function isBrowserAsset(rel) {
+/** Is this file part of what a browser fetches? The dev server serves the same set. */
+export function isBrowserAsset(rel) {
   if (rel.endsWith('.map')) return false
   if (rel === 'runtime-pin.json') return false
   if (rel.startsWith('meta/') || rel.startsWith(`meta\\`)) return false
@@ -74,9 +81,9 @@ function isBrowserAsset(rel) {
 }
 
 /**
- * Locate the built `dist/` behind a site-relative extension URL:
- * `/effects/entry.js` → `<project>/effects/dist/` or
- * `<project>/extensions/effects/dist/`, with `rest` the path inside it.
+ * Locate the workspace extension behind a site-relative extension URL —
+ * `/effects/entry.js` → the folder `./workspace-extension.js` finds for
+ * `effects` — with `distDir` its build and `rest` the path inside it.
  *
  * One lookup for both lanes that need the extension's build: this emitter, which
  * copies it into the site's output, and prerender, which imports it from where it
@@ -84,50 +91,57 @@ function isBrowserAsset(rel) {
  * cannot, by construction rather than by two lists kept in step by hand.
  *
  * @param {string} url - a site-relative URL, with any deployment base removed
- * @param {string} projectRoot - the directory holding the site and its extensions
- * @returns {{ distDir: string, urlBase: string, rest: string }|null}
+ * @param {string} projectRoot - the folder the site is in; the search starts
+ *   there and climbs to the workspace root
+ * @returns {{ distDir: string, urlBase: string, rest: string, packageDir: string, built: boolean }|null}
+ *   null when no workspace extension has that name; `built: false` when one does
+ *   and has no `dist/` yet
  */
 export function resolveExtensionDist(url, projectRoot) {
-  const parts = url.replace(/^\//, '').split('/')
-  if (parts.length < 2) return null
-  const pkgName = parts[0]
-
-  for (const candidate of [
-    join(projectRoot, pkgName, 'dist'),
-    join(projectRoot, 'extensions', pkgName, 'dist')
-  ]) {
-    if (existsSync(candidate)) {
-      return { distDir: candidate, urlBase: pkgName, rest: parts.slice(1).join('/') }
-    }
-  }
-  return null
+  const named = extensionNameOf(url)
+  if (!named) return null
+  const packageDir = findExtensionPackage(named.name, projectRoot)
+  if (!packageDir) return null
+  const distDir = join(packageDir, 'dist')
+  return { distDir, urlBase: named.name, rest: named.rest, packageDir, built: existsSync(distDir) }
 }
 
 /**
  * Files to emit for a site's declared extensions.
  *
- * Returns `{ fileName, source }` pairs for Rollup's `emitFile`, plus the
- * declarations that could not be resolved — the caller warns about those rather
- * than failing, because an absolute-URL extension is legitimately not ours to
- * emit and a missing workspace build is a warning the developer can act on.
+ * Returns `{ fileName, source }` pairs for Rollup's `emitFile`, plus what could
+ * not be emitted, for the caller to warn about rather than fail on: an
+ * absolute-URL extension is legitimately not ours to emit, and a missing or
+ * unbuilt workspace extension is something the developer can act on.
  *
- * @param {Array} extensions - `site.yml::extensions`, as declared.
+ * @param {Array} extensions - the payload's `config.extensions`.
  * @param {string} siteDir - the site package directory.
+ * @param {{ base?: string }} [options] - `base`: the deployment base the payload's
+ *   URLs carry. `dist/` has no base segment, so it is removed before the URL names
+ *   a folder — with `/docs/` left on, `/docs/effects/entry.js` named an extension
+ *   `docs`, and a site deployed under a subpath emitted none.
+ * @returns {{ emit: Array<{ fileName: string, source: Buffer }>, unresolved: string[],
+ *   unbuilt: Array<{ url: string, dir: string }> }}
  */
-export function collectExtensionAssets(extensions, siteDir) {
+export function collectExtensionAssets(extensions, siteDir, { base } = {}) {
   const emit = []
   const unresolved = []
-  if (!Array.isArray(extensions)) return { emit, unresolved }
+  const unbuilt = []
+  if (!Array.isArray(extensions)) return { emit, unresolved, unbuilt }
   const projectRoot = resolve(siteDir, '..')
 
   for (const decl of extensions) {
     if (!isSiteRelative(decl)) continue // absolute URL or a ref — someone else serves it
     const url = typeof decl === 'string' ? decl : decl.url
-    const found = resolveExtensionDist(url, projectRoot)
+    const found = resolveExtensionDist(stripBasePath(url, base), projectRoot)
     if (!found) {
       unresolved.push(url)
       continue
     }
+    if (!found.built) {
+      unbuilt.push({ url, dir: found.packageDir })
+      continue
+    }
     for (const rel of walk(found.distDir)) {
       if (!isBrowserAsset(rel)) continue
       emit.push({
@@ -136,5 +150,5 @@ export function collectExtensionAssets(extensions, siteDir) {
       })
     }
   }
-  return { emit, unresolved }
+  return { emit, unresolved, unbuilt }
 }

package/src/site/foundation-ref.js

@@ -13,8 +13,8 @@
  *
  * Three implementations of one question, none of which agreed, and the cause was
  * a pure function sitting behind a bundler import. So it moved here, with no
- * dependency beyond `node:fs` and `node:path`, the same reason `@uniweb/core`'s
- * `route-match` and `data-paths` are leaves.
+ * dependency beyond `node:fs`, `node:path` and the leaf package classifier, the
+ * same reason `@uniweb/core`'s `route-match` and `data-paths` are leaves.
  *
  * ## What it answers, and what it refuses
  *
@@ -30,6 +30,21 @@
 
 import { existsSync, readFileSync } from 'node:fs'
 import { resolve, join } from 'node:path'
+import { classifyPackage } from '../utils/classify-package.js'
+
+/**
+ * A folder found by NAME rather than named outright — a sibling of the site, or
+ * `foundations/<name>` — is the foundation only if it is one. A `file:` dep names
+ * its folder outright and is taken as written.
+ *
+ * ⛔ Until 2026-10-13 any folder of the right name passed. In a workspace holding
+ * `foundations/blog` and `sites/blog`, the site `sites/blog` resolved its
+ * foundation to ITSELF, and `sites/main` resolved it to the other site — while
+ * each site's `file:` dep named `foundations/blog` correctly, one check too late.
+ */
+function isFoundationDir(dir) {
+  return existsSync(dir) && classifyPackage(dir) === 'foundation'
+}
 
 /**
  * A catalog ref — `@org/name@version` — in its parts, or null for anything else.
@@ -174,7 +189,7 @@ export function detectFoundationType(foundation, siteRoot, { served = null } = {
 
   // Check if it's a local workspace sibling (directory name matches package name)
   const localPath = resolve(siteRoot, '..', name)
-  if (existsSync(localPath)) {
+  if (isFoundationDir(localPath)) {
     return {
       type: 'local',
       name,
@@ -201,7 +216,7 @@ export function detectFoundationType(foundation, siteRoot, { served = null } = {
 
   // Check in foundations/ directory (for multi-site projects)
   const foundationsPath = resolve(siteRoot, '..', '..', 'foundations', name)
-  if (existsSync(foundationsPath)) {
+  if (isFoundationDir(foundationsPath)) {
     return {
       type: 'local',
       name,
@@ -226,14 +241,18 @@ export function detectFoundationType(foundation, siteRoot, { served = null } = {
   // a registry ref, or a URL — none of the supported shapes. Fail with
   // guidance rather than fall through to a node_modules lookup that will
   // produce a confusing error later in the build.
+  const notFoundations = [localPath, foundationsPath].filter((dir) => existsSync(dir))
   throw new Error(
     `site.yml foundation: '${name}' did not resolve.\n` +
     `Foundations must be one of:\n` +
-    `  - a workspace-local sibling (a directory next to the site, named '${name}')\n` +
+    `  - a foundation next to the site, in a folder named '${name}'\n` +
     `  - a 'file:' dep in the site's package.json\n` +
-    `  - a directory in '../../foundations/${name}'\n` +
+    `  - a foundation in '../../foundations/${name}'\n` +
     `  - a versioned registry ref: '@org/${name}@<version>'\n` +
     `  - a full URL: 'https://...'\n` +
+    (notFoundations.length
+      ? `${notFoundations.join(' and ')} ${notFoundations.length > 1 ? 'exist' : 'exists'}, but not as a foundation package.\n`
+      : '') +
     `Foundations are runtime federated modules, not npm packages — there is no fall-through to node_modules.`
   )
 }

package/src/site/plugin.js

@@ -30,7 +30,7 @@
  * })
  */
 
-import { resolve, join } from 'node:path'
+import { resolve, join, relative, sep } from 'node:path'
 import { watch, existsSync } from 'node:fs'
 import { readFile, readdir } from 'node:fs/promises'
 import { resolveDefaultLocale, resolveFetchConfigs, DATA_DIR } from '@uniweb/core'
@@ -54,13 +54,38 @@ import { RECORDS_DIR, resolveRecordsDir } from './entity-pool.js'
 import { executeFetch, mergeDataIntoContent, toFetchList } from './data-fetcher.js'
 import { shouldSplitContent } from './split-content.js'
 import { FONT_LINKS_MARKER } from './head-markers.js'
-import { collectExtensionAssets } from './emit-extensions.js'
+import { collectExtensionAssets, isBrowserAsset } from './emit-extensions.js'
+import { extensionNameOf, findSiteExtension } from './workspace-extension.js'
 
 // BCP 47 locale code pattern: en, zh-CN, zh-Hant, pt-BR, fr-CA, sr-Latn, etc.
 const LOCALE_RE = '[a-z]{2,3}(?:-[A-Za-z]{2,4})?'
 
 const FAVICON_AUTODETECT = ['favicon.svg', 'favicon.ico', 'favicon.png']
 
+const EXTENSION_CONTENT_TYPES = {
+  js: 'text/javascript',
+  mjs: 'text/javascript',
+  css: 'text/css',
+  json: 'application/json',
+  svg: 'image/svg+xml',
+  png: 'image/png',
+  jpg: 'image/jpeg',
+  jpeg: 'image/jpeg',
+  gif: 'image/gif',
+  webp: 'image/webp',
+  avif: 'image/avif',
+  woff: 'font/woff',
+  woff2: 'font/woff2',
+  ttf: 'font/ttf',
+  otf: 'font/otf',
+  wasm: 'application/wasm'
+}
+
+/** The Content-Type the dev server answers an extension's built file with. */
+function extensionContentType(file) {
+  return EXTENSION_CONTENT_TYPES[file.split('.').pop()?.toLowerCase()] || 'application/octet-stream'
+}
+
 function faviconTypeFor(href) {
   const ext = href.split('?')[0].split('.').pop()?.toLowerCase()
   if (ext === 'svg') return 'image/svg+xml'
@@ -1022,6 +1047,71 @@ export function siteContentPlugin(options = {}) {
         console.error(`[dev-api] ${err.message}`)
       }
 
+      // A site-relative workspace extension (`/effects/entry.js`) is served from
+      // the site's own origin: the build copies its built files there
+      // (`collectExtensionAssets`, in generateBundle). Dev serves the same set,
+      // from the same folder, found by the same rule (`./workspace-extension.js`),
+      // so `uniweb dev` and `uniweb build` cannot disagree about whether a site
+      // has its extension. Its bare imports (`react`, `@uniweb/core`) resolve
+      // through the import map a dev page with extensions carries (`./config.js`,
+      // `serveInDev`). ⚠️ Synchronous, like the mount above, so it runs before
+      // Vite's SPA fallback.
+      //
+      // ⛔ Until 2026-10-13 nothing served it in dev: the request reached the SPA
+      // fallback, which answered `index.html` with a 200, `import()` failed on
+      // it, and the runtime dropped the extension. Measured on the `extensions`
+      // template.
+      const warnedExtensions = new Set()
+      devServer.middlewares.use(async (req, res, next) => {
+        const declared = siteContent?.config?.extensions
+        const named = Array.isArray(declared) && declared.length ? extensionNameOf(req.url, basePath) : null
+        const entry =
+          named &&
+          declared
+            .map((d) => (typeof d === 'string' ? d : d?.url))
+            .find((url) => extensionNameOf(url, basePath)?.name === named.name)
+        if (!entry || !named.rest) return next()
+
+        const packageDir = findSiteExtension(named.name, resolvedSitePath)
+        if (packageDir) {
+          const distDir = join(packageDir, 'dist')
+          let rest = named.rest
+          try {
+            rest = decodeURIComponent(rest)
+          } catch {}
+          const file = resolve(distDir, rest)
+          if (file.startsWith(distDir + sep) && isBrowserAsset(rest) && existsSync(file)) {
+            try {
+              const body = await readFile(file)
+              res.setHeader('Content-Type', extensionContentType(file))
+              res.setHeader('Cache-Control', 'no-cache')
+              res.end(body)
+              return
+            } catch (err) {
+              return next(err)
+            }
+          }
+        }
+
+        // Only the declared entry is answered when its file is missing: the runtime
+        // drops an extension it cannot load either way, and a 404 says what the
+        // SPA's HTML would hide. Any other path under that name is left to Vite.
+        if (extensionNameOf(entry, basePath)?.rest !== named.rest) return next()
+        if (!warnedExtensions.has(entry)) {
+          warnedExtensions.add(entry)
+          console.warn(
+            packageDir
+              ? `[site-content] Extension '${entry}' is not built (${relative(resolvedSitePath, packageDir)}). ` +
+                  `Build it — \`uniweb build\` from the workspace root — and reload.`
+              : `[site-content] Extension '${entry}' is site-relative, and no workspace extension has its name. ` +
+                  `A site finds one in <name>/ or extensions/<name>/, in the folder the site is in or a folder ` +
+                  `above it, up to the workspace root.`
+          )
+        }
+        res.statusCode = 404
+        res.end()
+      })
+
       // Watch for content changes in dev mode
       if (shouldWatch) {
         // Debounce rebuilds. One that `queries.yml` or `site.yml` asked for also
@@ -1681,17 +1771,26 @@ export function siteContentPlugin(options = {}) {
       // Without this the build succeeds, prerender renders the extension's
       // sections from the workspace, and the browser then 404s and replaces
       // them with `Component not found` on hydration.
-      const { emit, unresolved } = collectExtensionAssets(
+      const { emit, unresolved, unbuilt } = collectExtensionAssets(
         finalContent.config?.extensions,
-        resolve(sitePath)
+        resolve(sitePath),
+        { base: finalContent.config?.base }
       )
       for (const asset of emit) {
         this.emitFile({ type: 'asset', fileName: asset.fileName, source: asset.source })
       }
       for (const url of unresolved) {
         this.warn(
-          `Extension '${url}' is site-relative but no built extension was found for it. ` +
-            `The site will 404 on it at runtime — build the extension, or reference it by URL.`
+          `Extension '${url}' is site-relative, and no workspace extension has its name. ` +
+            `A site finds one in <name>/ or extensions/<name>/, in the folder the site is in or a folder ` +
+            `above it, up to the workspace root. The site will 404 on it at runtime — move the extension ` +
+            `there, or reference it by URL.`
+        )
+      }
+      for (const { url, dir } of unbuilt) {
+        this.warn(
+          `Extension '${url}' is not built (${relative(resolve(sitePath), dir) || dir}), so the site will ` +
+            `404 on it at runtime. Run \`uniweb build\` from the workspace root, which builds extensions first.`
         )
       }
     },

package/src/site/workspace-extension.js

@@ -0,0 +1,142 @@
+/**
+ * Where a site finds a WORKSPACE extension — the one rule, asked by every lane.
+ *
+ * A site declares a workspace extension by the URL it serves it at
+ * (`extensions: ['/effects/entry.js']`) or by name (`extensions: [effects]`).
+ * Either way the extension's name is `effects`, and this module answers which
+ * folder of the workspace holds it. Each lane that needs that answer asks here:
+ * the site build, which copies the extension's build into the site's output
+ * (`emit-extensions.js`); prerender, which imports it (`../prerender.js`); the
+ * dev server, which serves it (`plugin.js`); and the CLI — `add extension`
+ * deciding whether a site can load what it just made, `doctor`, and `push` /
+ * `publish` bringing a named extension along.
+ *
+ * ── The rule ──
+ *
+ * The extension named `<name>` is the nearest `<name>/` or `extensions/<name>/`
+ * that is a foundation package — looking first in the folder the site is in,
+ * then in each folder above it, up to the workspace root:
+ *
+ *   project/                     ← the workspace root (pnpm-workspace.yaml)
+ *   ├── extensions/effects/      ← what sites/main loads as /effects/entry.js
+ *   ├── sites/main/
+ *   └── docs/
+ *       ├── effects/             ← what docs/site loads: it is nearer
+ *       └── site/
+ *
+ * ── Why each part ──
+ *
+ * - **Nearest first**, so a co-located project can keep its own extension under
+ *   a name a shared one also has — the way a nearer `node_modules` wins.
+ * - **Up to the workspace root and no further** — the folder holding
+ *   `pnpm-workspace.yaml`, or a `package.json` that lists `workspaces`, the same
+ *   marker the CLI finds a workspace by. A folder outside the project is never
+ *   part of it, and a site in no workspace looks only in the folder it is in.
+ * - **A foundation package, not any folder of that name** (`classifyPackage`):
+ *   an extension is a foundation. A built SITE named `effects` has a `dist/` as
+ *   well, and the more folders the search visits, the likelier a same-named one
+ *   that is not the extension.
+ *
+ * ⛔ Until 2026-10-13 the build looked only in the folder the site is in, and
+ * `add extension` judged an extension reachable from the workspace root — so a
+ * site at `sites/main` was wired to `extensions/effects`, which its build then
+ * could not find. The rule was written three times — this lookup, `add`'s check
+ * and `doctor`'s parsing of the URL — and they disagreed. It is written once now.
+ *
+ * Node built-ins only, beside the leaf classifier, so any lane can import it
+ * without pulling in Vite.
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { classifyPackage } from '../utils/classify-package.js'
+import { stripBasePath } from './extension-urls.js'
+
+/** A folder holding a workspace manifest — what the CLI finds a workspace by. */
+function isWorkspaceRoot(dir) {
+  if (existsSync(join(dir, 'pnpm-workspace.yaml'))) return true
+  const pkgPath = join(dir, 'package.json')
+  if (!existsSync(pkgPath)) return false
+  try {
+    return Array.isArray(JSON.parse(readFileSync(pkgPath, 'utf8')).workspaces)
+  } catch {
+    return false
+  }
+}
+
+/** One folder name — never a path, so a declaration cannot walk the search out of a folder. */
+function isExtensionName(name) {
+  return typeof name === 'string' && name !== '' && name !== '.' && name !== '..' && !/[\\/]/.test(name)
+}
+
+/**
+ * The folders a site searches for a workspace extension, nearest first.
+ *
+ * @param {string} fromDir - the folder the site is in
+ * @returns {string[]} `fromDir`, then each folder above it up to and including
+ *   the workspace root — or `fromDir` alone when no workspace holds it
+ */
+export function extensionSearchDirs(fromDir) {
+  const start = resolve(fromDir)
+  const dirs = []
+  for (let dir = start; ; dir = dirname(dir)) {
+    dirs.push(dir)
+    if (isWorkspaceRoot(dir)) return dirs
+    if (dirname(dir) === dir) return [start]
+  }
+}
+
+/**
+ * Every folder that could hold the extension named `name`, in the order they are
+ * tried — for a message that says where the build looked.
+ *
+ * @param {string} name - the extension's name: its folder, and its URL's first segment
+ * @param {string} fromDir - the folder the site is in
+ * @returns {string[]}
+ */
+export function extensionCandidates(name, fromDir) {
+  if (!isExtensionName(name)) return []
+  return extensionSearchDirs(fromDir).flatMap((dir) => [join(dir, name), join(dir, 'extensions', name)])
+}
+
+/**
+ * The folder of the workspace extension named `name`, or null.
+ *
+ * @param {string} name
+ * @param {string} fromDir - the folder the site is in
+ * @returns {string|null} an absolute package folder; built or not — the caller
+ *   that needs its `dist/` checks for it, so "not built" is never reported as
+ *   "not found"
+ */
+export function findExtensionPackage(name, fromDir) {
+  for (const candidate of extensionCandidates(name, fromDir)) {
+    if (existsSync(candidate) && classifyPackage(candidate) === 'foundation') return candidate
+  }
+  return null
+}
+
+/**
+ * {@link findExtensionPackage} for a site named by its own folder.
+ *
+ * @param {string} name
+ * @param {string} siteDir - the site's folder
+ * @returns {string|null}
+ */
+export function findSiteExtension(name, siteDir) {
+  return findExtensionPackage(name, dirname(resolve(siteDir)))
+}
+
+/**
+ * The extension name a site-relative URL refers to: its first segment, once the
+ * deployment base is removed (`/docs/effects/entry.js` at base `/docs/` → `effects`).
+ *
+ * @param {string} url - a site-relative URL, as declared or as the payload carries it
+ * @param {string} [base] - the site's deployment base
+ * @returns {{ name: string, rest: string } | null} null when the URL names no file inside a folder
+ */
+export function extensionNameOf(url, base) {
+  if (typeof url !== 'string' || !url.startsWith('/') || url.startsWith('//')) return null
+  const parts = stripBasePath(url, base).replace(/^\//, '').split(/[?#]/)[0].split('/')
+  if (parts.length < 2 || !isExtensionName(parts[0])) return null
+  return { name: parts[0], rest: parts.slice(1).join('/') }
+}