@uniweb/build 1.1.0 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -56,15 +56,15 @@
     "js-yaml": "^4.1.0",
     "sharp": "^0.35.3",
     "yaml": "^2.5.0",
-    "@uniweb/theming": "~1.1.0",
-    "@uniweb/semantic-parser": "~1.5.1",
-    "@uniweb/schemas": "~1.0.1",
-    "@uniweb/projections": "~1.1.0",
-    "@uniweb/content-reader": "~1.2.8",
-    "@uniweb/content-writer": "~1.0.1"
+    "@uniweb/semantic-parser": "~1.6.0",
+    "@uniweb/theming": "~1.2.0",
+    "@uniweb/schemas": "~1.1.0",
+    "@uniweb/projections": "~1.1.1",
+    "@uniweb/content-reader": "~1.3.0",
+    "@uniweb/content-writer": "~1.1.0"
   },
   "optionalDependencies": {
-    "@uniweb/runtime": "~1.1.0"
+    "@uniweb/runtime": "~1.1.1"
   },
   "peerDependencies": {
     "vite": "^5.0.0 || ^6.0.0 || ^7.0.0",
@@ -73,8 +73,8 @@
     "@tailwindcss/vite": "^4.0.0",
     "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
     "vite-plugin-svgr": "^4.0.0",
-    "@uniweb/core": "~1.1.0",
-    "@uniweb/runtime": "~1.1.0"
+    "@uniweb/core": "~1.2.0",
+    "@uniweb/runtime": "~1.1.1"
   },
   "peerDependenciesMeta": {
     "vite": {

package/src/i18n/freeform.js

@@ -26,6 +26,7 @@ import { poolDirsForSchema, schemaForPoolDirs, RECORDS_DIR } from '../site/entit
 import { parseFrontmatter } from '../utils/frontmatter.js'
 import { computeSourceHash } from './freeform-manifest.js'
 import { layoutAreaRoute } from '../site/layout-folder.js'
+import { warnOutsideVocabulary } from '../site/vocabulary-warnings.js'
 
 // Try to import content-reader for markdown → ProseMirror conversion
 let markdownToProseMirror
@@ -46,6 +47,11 @@ try {
 }
 
 
+/** Report what a translation's markdown could not honour, naming the file. */
+function warnFor(filePath) {
+  return (message) => console.warn(`[i18n] ${relative(process.cwd(), filePath)}: ${message}`)
+}
+
 /**
  * Normalize route for filesystem path
  * Removes leading slash, replaces remaining slashes with path separators
@@ -83,8 +89,10 @@ export async function loadFreeformTranslation(section, page, locale, localesDir)
       const content = await readFile(filePath, 'utf-8')
       const { frontmatter, body } = parseFrontmatter(content, filePath)
 
-      // Convert markdown body to ProseMirror
-      const proseMirrorContent = markdownToProseMirror(body)
+      // Convert markdown body to ProseMirror — HTML in it shows as written,
+      // except `<br>`, and the translator is told which file.
+      const proseMirrorContent = markdownToProseMirror(body, { onWarning: warnFor(filePath) })
+      warnOutsideVocabulary(proseMirrorContent, warnFor(filePath))
 
       return {
         content: proseMirrorContent,
@@ -138,7 +146,8 @@ export async function loadFreeformRecord(item, schema, locale, localesDir) {
     const { frontmatter, body } = parseFrontmatter(content, filePath)
 
     // Convert markdown body to ProseMirror (if body exists)
-    const proseMirrorContent = body.trim() ? markdownToProseMirror(body) : null
+    const proseMirrorContent = body.trim() ? markdownToProseMirror(body, { onWarning: warnFor(filePath) }) : null
+    if (proseMirrorContent) warnOutsideVocabulary(proseMirrorContent, warnFor(filePath))
 
     return {
       frontmatter: Object.keys(frontmatter).length > 0 ? frontmatter : null,

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/content-collector.js

@@ -42,6 +42,7 @@ import { authoredRedirectTarget } from '@uniweb/core/resolve-route'
 import { parseFrontmatter } from '../utils/frontmatter.js'
 import { parseGrid } from '@uniweb/schemas/grid'
 import { runtimeServicesConfig, refuseRetiredServiceKeys, refuseUnreadableServices } from '../uwx/services-request.js'
+import { warnOutsideVocabulary } from './vocabulary-warnings.js'
 
 // Try to import content-reader, fall back to simplified parser
 let markdownToProseMirror
@@ -1068,7 +1069,12 @@ async function processMarkdownFile(filePath, id, siteRoot, defaultStableId = nul
   // come through here (a free-form translation, a record body) kept raw references
   // nothing resolved, and the same section's content differed between a build and a
   // document stored as written.
-  const proseMirrorContent = markdownToProseMirror(markdown)
+  //
+  // HTML in the markdown is not content: it shows as written, except `<br>`
+  // (content-reader, since 2026-10-14). Say so with the file in hand.
+  const warnHere = (message) => console.warn(`[content-collector] ${relative(siteRoot, filePath)}: ${message}`)
+  const proseMirrorContent = markdownToProseMirror(markdown, { onWarning: warnHere })
+  warnOutsideVocabulary(proseMirrorContent, warnHere)
 
   // `query: team` → `fetch: { query: team }`; a list, one config per name, each under
   // its own `as` — the one helper every level uses. Unrelated to a section type's

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/query-processor.js

@@ -72,6 +72,7 @@ import { toDeliveredRecord, toStoredRecord, storedPath, briefFieldMap, contentBo
 import { collectNestedRefs } from '@uniweb/schemas/format'
 import { labelIn } from './entry-label.js'
 import { fileRecordValue, makeFilePreview } from './file-records.js'
+import { warnOutsideVocabulary } from './vocabulary-warnings.js'
 
 // Try to import content-reader for markdown parsing
 let markdownToProseMirror
@@ -563,8 +564,11 @@ async function processContentItem(dir, filename, config, siteRoot, basePath, rec
   // record was published.
   await processDataItemAssets(frontmatter, filepath, siteRoot, recordsRoot, basePath)
 
-  // Parse markdown body to ProseMirror
-  const content = markdownToProseMirror(body)
+  // Parse markdown body to ProseMirror — HTML in it shows as written, except
+  // `<br>`, and the author is told which file.
+  const warnHere = (message) => console.warn(`[records] ${relative(siteRoot, filepath)}: ${message}`)
+  const content = markdownToProseMirror(body, { onWarning: warnHere })
+  warnOutsideVocabulary(content, warnHere)
 
   // Process assets (resolve paths, copy co-located files)
   // This modifies content in place, updating paths to site-root-relative

package/src/site/vocabulary-warnings.js

@@ -0,0 +1,33 @@
+/**
+ * Say, with the file in hand, what in a document a page leaves out.
+ *
+ * A document holds the rich-text vocabulary (`@uniweb/content-reader/vocabulary`):
+ * its types and attributes, and the values that reach a page's markup. What is
+ * outside it — a link to `javascript:`, an inert `{.name}`, MathML outside the
+ * allowlist — the renderer leaves out of the page, and a backend that cleans the
+ * content it stores removes, so the next pull would write the file without it.
+ * The author hears it here first, once per thing, naming the file.
+ */
+import { outsideVocabulary } from '@uniweb/content-reader/vocabulary'
+
+const SAYS = {
+  url: (f) => `a link to \`${f.found}\` is never followed`,
+  target: (f) => `\`target=${f.found}\` is not a link target`,
+  'style-name': (f) => `\`{${f.found}}\` is not a style name`,
+  color: (f) => `\`${f.found}\` is not a colour`,
+  mathml: (f) => `a formula's MathML holds what a page cannot show (${f.found})`,
+  'ref-id': (f) => `\`${f.found}\` is not an inset reference`,
+}
+
+/**
+ * Warn, for each thing in `doc` outside the vocabulary, with the file it came from.
+ *
+ * @param {Object} doc - a ProseMirror document
+ * @param {(message: string) => void} warn - prints one message, prefixed with the file
+ */
+export function warnOutsideVocabulary(doc, warn) {
+  for (const finding of outsideVocabulary(doc)) {
+    const says = SAYS[finding.rule]?.(finding) ?? `\`${finding.found}\` is not part of a document (${finding.rule})`
+    warn(`${says} — a page leaves it out, and a backend that cleans what it stores removes it`)
+  }
+}

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('/') }
+}

package/src/uwx/data-schema.js

@@ -27,7 +27,8 @@ const TEXT_KINDS = new Set(['string', 'text'])
 // Rich-content `format` markers on a `text` field — the file-based body shape that
 // replaced the retired `richtext` kind (2026-06-02 / uwx-format.md). A `text` field
 // carrying one round-trips as the RAW source string (no ProseMirror conversion).
-const CONTENT_TEXT_FORMATS = new Set(['markdown', 'html'])
+// ⛔ `html` was one until 2026-10-14; `@uniweb/schemas` refuses it by name since.
+const CONTENT_TEXT_FORMATS = new Set(['markdown'])
 
 // The field an open map's key lowers into. `name` matches the idiom already in use
 // for this shape (the backend's site-content `collections` section), so an open map
@@ -113,7 +114,7 @@ export function isContentBodyField(field) {
  *   (item_ref) ref to its full `@org/model/<section>` path. Falls back to
  *   `resolveName` (model only) when not supplied.
  * @returns {Object} the declaration (`{ name, label?, plural?, icon?, description?,
- *          source_locale?, linkable?, sections }`).
+ *          source_locale?, linkable?, grantable?, sections }`).
  */
 export function toDataSchemaDeclaration(normalized, { name, resolveName, resolveOptions } = {}) {
   if (!name) throw new Error('toDataSchemaDeclaration: a registry name is required')
@@ -158,6 +159,10 @@ export function toDataSchemaDeclaration(normalized, { name, resolveName, resolve
   // reference, which read as a promise that one is accepted. A backend refuses it.
   if (normalized.linkable === false) decl.linkable = false
 
+  // `grantable` — AUTHORED ONLY, like `linkable`: a model's entries may be shared one at a
+  // time unless it says `grantable: false` (omitted ⇒ true) [Diego, 2026-10-14].
+  if (normalized.grantable === false) decl.grantable = false
+
   decl.sections = sections
   return decl
 }
@@ -424,6 +429,9 @@ function lowerLeaf(field, resolve, optResolve, { multiple = false } = {}) {
   if (leafType === 'ref') {
     out.type = 'entity_ref'
     if (field.ref) out.model = resolve(field.ref)
+    // The level on the entry it points to that opens this entry, for `read` — by link
+    // [Diego, 2026-10-14]. `@uniweb/schemas` admits it only here, as read, edit or admin.
+    if (field.readable_with) out.readable_with = field.readable_with
     return out
   }
 

package/src/uwx/site-project.js

@@ -47,7 +47,8 @@ import { declarationsToQueriesYml } from './records-project.js'
 import { FILLED_SECTION_TYPE, buildRouteOf } from './site.js'
 import { translationContext, SITE_META_CONTEXT } from '../i18n/extract.js'
 import { authorableDeclaration, DECLARATION_KEYS } from '../site/fetch-shapes.js'
-import { createTranslationCollector, writeLocaleTranslations, writeFreeformTranslations, unwrapLocalizedContent } from './locale-sync.js'
+import { createTranslationCollector, writeLocaleTranslations, writeFreeformTranslations, unwrapLocalizedContent, isProseMirrorDoc } from './locale-sync.js'
+import { unwritableNodes } from '@uniweb/content-writer'
 import { buildFreeformPath, freeformPathsFor } from '../i18n/freeform.js'
 import { unwrapLocalized, unwrapLocalizedList } from './backfill.js'
 import { LOCALIZED_FIELD_ASSUMPTION } from './localize.js'
@@ -1201,6 +1202,59 @@ function projectLayout(layoutSections, layoutBaseDir, report, prune, ctx) {
   if (prune && written.length > 0) pruneOrphanLayout(layoutBaseDir, new Set(written), report)
 }
 
+/**
+ * ⛔ A PULL THAT WOULD DROP CONTENT WRITES NOTHING.
+ *
+ * A node a markdown file cannot hold is left out of the file it is written to,
+ * and the push after the pull then deletes it from the site — with nobody told
+ * but a log line. So every section document the projection would write is asked
+ * first (`unwritableNodes`, `@uniweb/content-writer`), every locale's included,
+ * and the pull stops, naming each section and what it holds.
+ * ⛔ Until 2026-10-14 the writer logged one line per type and the pull went on:
+ * measured with a button an editor saved as a node, which a pull and a push then
+ * deleted.
+ *
+ * @param {object} document - the `@uniweb/site-content` document
+ * @param {string} sourceLocale
+ */
+function refuseContentFilesCannotHold(document, sourceLocale) {
+  const found = []
+  const name = (record, where) => {
+    const own = record?.slug !== undefined ? pageDirName(record, sourceLocale) : record?.stable_id || record?.$uuid
+    return own ? (where ? `${where}/${own}` : String(own)) : where
+  }
+  const visit = (value, where) => {
+    if (Array.isArray(value)) {
+      for (const item of value) visit(item, where)
+      return
+    }
+    if (!value || typeof value !== 'object') return
+    const here = name(value, where)
+    for (const [key, field] of Object.entries(value)) {
+      if (key === 'content') {
+        const docs = isProseMirrorDoc(field)
+          ? [field]
+          : isPlainRecord(field)
+            ? Object.values(field).filter(isProseMirrorDoc)
+            : []
+        const types = [...new Set(docs.flatMap((doc) => unwritableNodes(doc)))]
+        if (types.length) found.push(`${here || 'a section'}: ${types.join(', ')}`)
+        if (docs.length) continue
+      }
+      visit(field, here)
+    }
+  }
+  visit(document?.pages, '')
+  visit(document?.layout_sections, 'layout')
+  if (found.length === 0) return
+  throw new Error(
+    'This pull would leave content out of your files — a file cannot hold it, so your next push would ' +
+      'delete it from the site. Nothing was written.\n' +
+      found.map((entry) => `  ${entry}`).join('\n') +
+      '\nChange or remove it where it was made, then pull again.'
+  )
+}
+
 /**
  * Project a whole `@uniweb/site-content` document to a site's files: `info` →
  * config (siteInfoToConfig), `collections[]` declarations →
@@ -1226,6 +1280,9 @@ function projectLayout(layoutSections, layoutBaseDir, report, prune, ctx) {
  * @returns {{ config: object, collections: object, locales: object, pages: string[], sections: string[], layout: string[], deleted: string[], renamed: object[] }}
  */
 export function siteContentDocumentToProject({ document, siteRoot, backend = null, sourceLocale = LOCALIZED_FIELD_ASSUMPTION.defaultSourceLocale, prune = false, keepAuthoredFoundation = false, scope, dataModel = null }) {
+  // Before anything is written: a pull that would leave content out of the files stops here.
+  refuseContentFilesCannotHold(document, sourceLocale)
+
   const report = { config: null, collections: null, locales: null, assets: null, pages: [], sections: [], layout: [], deleted: [], renamed: [] }
 
   // Collects target-locale translations of localized scalars as they're projected;