@uniweb/build 0.42.0 → 0.43.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.42.0",
+  "version": "0.43.0",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -64,7 +64,7 @@
     "@uniweb/theming": "^0.1.15"
   },
   "optionalDependencies": {
-    "@uniweb/runtime": "^0.18.0"
+    "@uniweb/runtime": "^0.19.0"
   },
   "peerDependencies": {
     "vite": "^5.0.0 || ^6.0.0 || ^7.0.0",
@@ -73,7 +73,7 @@
     "@tailwindcss/vite": "^4.0.0",
     "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
     "vite-plugin-svgr": "^4.0.0",
-    "@uniweb/core": "^0.24.0"
+    "@uniweb/core": "^0.24.1"
   },
   "peerDependenciesMeta": {
     "vite": {

package/src/foundation/derive-supports.js

@@ -0,0 +1,259 @@
+/**
+ * Derive the host services a foundation is built against, from its own bundle.
+ *
+ * ## The one idea
+ *
+ * A foundation declares `uniweb.supports` in `package.json` so a consumer can
+ * tell "this foundation draws a search box" from "this foundation has never
+ * heard of search". The declaration is authored, and an author who never learns
+ * the key exists never writes one — which is the failure the field was added to
+ * prevent, reappearing one level up.
+ *
+ * ⭐ **But the bundler already knows.** `@uniweb/kit` is not externalized
+ * (`DEFAULT_EXTERNALS` is the react entries plus the bare `@uniweb/core`), so
+ * kit's service code is compiled into the foundation and tree-shaken with it.
+ * A module that survives that shake is a module something reachable uses.
+ *
+ * So this reads the answer off the module graph instead of asking for it, and
+ * `package.json` becomes the *supplement* for what the graph cannot see rather
+ * than the declaration itself.
+ *
+ * ## ⛔ POST-TREE-SHAKE ONLY — the pre-shake graph OVER-REPORTS
+ *
+ * Rollup parses modules it later discards, so `getModuleIds()` includes code
+ * that was shaken out. Measured 2026-09-06 on `templates/services`, which uses
+ * submit and not search:
+ *
+ * | scanned | literals found |
+ * |---|---|
+ * | the whole graph (`getModuleIds()`) | ⛔ `search, submit` |
+ * | survivors only (`renderedLength > 0`) | ✅ `submit` |
+ *
+ * 475 modules parsed, 28 survived. ⇒ **Over-reporting is the dangerous
+ * direction** — it tells a host to offer a service the foundation never draws,
+ * which is exactly the invisible failure this whole mechanism exists to stop.
+ * Never widen the scan set to "everything Rollup saw".
+ *
+ * ## ⭐ The service name travels with the code, so there is almost no map
+ *
+ * `kit/src/utils/submitTarget.js` contains `resolveService(website, 'submit')`
+ * in its own source and survives beside the hook that pulled it in. So scanning
+ * survivors for that call recovers the name without anyone maintaining a
+ * module→service table — and it covers the **open registry** for free: a
+ * foundation that invents `booking` is read the same way as one that uses
+ * `submit`, because the framework has no list of permitted names
+ * (`core/src/services.js`).
+ *
+ * Two gates need help, and only two:
+ *
+ *   - **`useTracker`** resolves nothing itself — it calls through to
+ *     `getUniweb()?.tracking`, and the `'tracking'` literal lives in
+ *     `runtime/src/wire-foundation.js`, which is never bundled into a
+ *     foundation. Its module presence is the signal.
+ *   - **`isSearchEnabled()`** is a `Website` method, and its literal is in
+ *     `core/src/website.js` — external, so never a survivor. The call is the
+ *     signal.
+ *
+ * ⚠️ `@uniweb/api` deliberately needs no entry: it calls
+ * `resolveService(website, SERVICE_NAME)` against a module-level `const`, which
+ * `readModuleConsts` resolves. Without that resolution `api` would be both
+ * missed *and* counted as blindness, marking every foundation that uses it
+ * unknowable.
+ *
+ * ## Why the AST rather than a regex
+ *
+ * The probe that produced the table above also found its only "computed call
+ * site" inside a **JSDoc comment** in `core/src/services.js` describing the
+ * signature, and `export function resolveService(website, name)` is a
+ * declaration a regex reads as a call with a variable argument. Both vanish on
+ * an AST, and Rollup has already parsed every module — `info.ast` was present
+ * for all 475 — so this costs a walk, not a parse.
+ *
+ * @module @uniweb/build/foundation/derive-supports
+ */
+
+/** Kit's `useTracker`, in a workspace clone or a published install alike. */
+const TRACKER_MODULE = /(^|[/\\])kit[/\\]src[/\\]hooks[/\\]useTracker\.js$/
+
+/**
+ * Walk an ESTree tree, visiting every node.
+ *
+ * Hand-rolled rather than pulled from a dependency: `@uniweb/build` is on the
+ * install path of every foundation, and this is a dozen lines.
+ */
+function walk(node, visit) {
+  if (!node || typeof node !== 'object') return
+  if (Array.isArray(node)) {
+    for (const child of node) walk(child, visit)
+    return
+  }
+  if (typeof node.type === 'string') visit(node)
+  for (const key in node) {
+    if (key === 'type' || key === 'loc' || key === 'range' || key === 'start' || key === 'end') {
+      continue
+    }
+    const value = node[key]
+    if (value && typeof value === 'object') walk(value, visit)
+  }
+}
+
+/**
+ * Module-scope `const NAME = 'string'` bindings.
+ *
+ * ⛔ Top level only, deliberately. A nested binding of the same name would
+ * shadow, and resolving one could name a service the code never asks for —
+ * over-reporting, the direction that must not happen. An unresolved identifier
+ * is treated as blindness instead, which is the safe answer.
+ */
+function readModuleConsts(ast) {
+  const consts = new Map()
+  const record = (decl) => {
+    if (!decl || decl.type !== 'VariableDeclaration') return
+    for (const d of decl.declarations || []) {
+      if (d.id?.type === 'Identifier' && typeof d.init?.value === 'string') {
+        consts.set(d.id.name, d.init.value)
+      }
+    }
+  }
+  for (const node of ast.body || []) {
+    record(node)
+    if (node.type === 'ExportNamedDeclaration') record(node.declaration)
+  }
+  return consts
+}
+
+/** `resolveService(...)`, called bare or through a namespace. */
+function isResolveServiceCall(node) {
+  if (node.type !== 'CallExpression') return false
+  const callee = node.callee
+  if (callee?.type === 'Identifier') return callee.name === 'resolveService'
+  if (callee?.type === 'MemberExpression' && !callee.computed) {
+    return callee.property?.name === 'resolveService'
+  }
+  return false
+}
+
+/** A `.isSearchEnabled()` call on anything. */
+function isSearchEnabledCall(node) {
+  return (
+    node.type === 'CallExpression' &&
+    node.callee?.type === 'MemberExpression' &&
+    !node.callee.computed &&
+    node.callee.property?.name === 'isSearchEnabled'
+  )
+}
+
+/**
+ * The set of modules that contributed code to the written bundle.
+ *
+ * `renderedLength > 0` is the discriminator: a module whose every binding was
+ * shaken out contributes nothing, and counting it would reintroduce exactly the
+ * over-reporting this module exists to avoid.
+ */
+function collectSurvivors(bundle) {
+  const survivors = new Set()
+  for (const chunk of Object.values(bundle || {})) {
+    if (chunk?.type !== 'chunk' || !chunk.modules) continue
+    for (const [id, mod] of Object.entries(chunk.modules)) {
+      if (mod?.renderedLength > 0) survivors.add(id)
+    }
+  }
+  return survivors
+}
+
+/**
+ * Derive the services this foundation reaches for.
+ *
+ * @param {object} bundle - Rollup's bundle, as handed to `writeBundle`
+ * @param {object} ctx - the Rollup plugin context (`this` in the hook)
+ * @returns {{services: string[], blind: boolean, blindAt: string[]}}
+ *   `services` is sorted and de-duplicated, and is a **lower bound**.
+ *   `blind` is true when a `resolveService` call names its service with
+ *   something this cannot read — the one case where the lower bound is known to
+ *   be incomplete, and the caller must not report an empty result as a proven
+ *   "none". `blindAt` names the modules, for the warning.
+ */
+export function deriveSupports(bundle, ctx) {
+  const services = new Set()
+  const blindAt = new Set()
+
+  for (const id of collectSurvivors(bundle)) {
+    if (TRACKER_MODULE.test(id)) services.add('tracking')
+
+    const info = ctx?.getModuleInfo?.(id)
+    const ast = info?.ast
+    if (!ast) continue
+
+    const consts = readModuleConsts(ast)
+
+    walk(ast, (node) => {
+      if (isSearchEnabledCall(node)) {
+        services.add('search')
+        return
+      }
+      if (!isResolveServiceCall(node)) return
+
+      const arg = node.arguments?.[1]
+      if (typeof arg?.value === 'string') {
+        services.add(arg.value)
+      } else if (arg?.type === 'Identifier' && consts.has(arg.name)) {
+        services.add(consts.get(arg.name))
+      } else {
+        // A name this cannot read. Not an error — a foundation may legitimately
+        // compute one — but it means the derived set is short by an unknown
+        // amount, and the caller has to say so rather than claim completeness.
+        blindAt.add(id)
+      }
+    })
+  }
+
+  return {
+    services: [...services].sort(),
+    blind: blindAt.size > 0,
+    blindAt: [...blindAt].sort(),
+  }
+}
+
+/**
+ * Compose what the foundation publishes from the authored and derived halves.
+ *
+ * ## ⛔ THE THREE STATES SURVIVE, AND TWO OF THEM ARE NOT THE SAME
+ *
+ * `info.supports` carries three values and a consumer distinguishes all of them:
+ * **absent** is UNKNOWN — nobody said — **`[]`** is an explicit none, and a list
+ * is *these and only these*. Returning `{}` versus `{ supports: [] }` is how
+ * that distinction reaches the wire, so neither branch below may be collapsed
+ * into the other. It is the same three-state rule `info.runtime` states in the
+ * same brief: an omission is UNKNOWN rather than unconstrained, because a floor
+ * nobody stated cannot be shown to be satisfied.
+ *
+ * | authored | derived | emitted |
+ * |---|---|---|
+ * | absent | some | the derived set |
+ * | absent | none, nothing blind | ⭐ `[]` — a **proven** none, not an assumed one |
+ * | absent | none, something blind | ⛔ nothing — UNKNOWN, honestly |
+ * | a list | any | the union |
+ * | `[]` | some | the union, with a warning: the evidence contradicts the claim |
+ *
+ * ⭐ **The union only ever grows the set**, so the failure the authored-only
+ * design guarded against — publishing a set shorter than the truth — stays
+ * unreachable: whatever a developer wrote is still there.
+ *
+ * @param {string[]|undefined} authored - normalized `uniweb.supports`; `undefined` when absent
+ * @param {{services: string[], blind: boolean}|null} derived - null when not derived (a dev rebuild)
+ * @returns {{supports?: string[]}} spread into `_self`; `{}` keeps the key absent
+ */
+export function composeSupports(authored, derived) {
+  // No derivation ran (dev rebuild): the authored value is the whole answer,
+  // and an absent one stays absent.
+  if (!derived) return authored === undefined ? {} : { supports: authored }
+
+  const { services, blind } = derived
+
+  if (authored === undefined && services.length === 0) {
+    return blind ? {} : { supports: [] }
+  }
+
+  const union = [...new Set([...(authored || []), ...services])].sort()
+  return { supports: union }
+}

package/src/import-map-plugin.js

@@ -11,7 +11,7 @@
  * Used by:
  * - Site builds (runtime mode + extensions)  — packages/build/src/site/config.js
  * - Runtime shell build                      — packages/runtime/vite.config.app.js
- * - Dynamic-runtime (editor preview)         — packages/uniweb-editor/dynamic-runtime/
+ * - An authoring tool's live preview          — its own runtime build
  *
  * @module @uniweb/build/import-map-plugin
  */

package/src/schema.js

@@ -17,6 +17,7 @@ import { join, dirname, extname, basename } from 'node:path'
 import { pathToFileURL } from 'node:url'
 import { inferTitle } from './utils/infer-title.js'
 import { collectSchemaRefs, buildDataSchemaMap } from './resolve-data-schema.js'
+import { composeSupports } from './foundation/derive-supports.js'
 
 // Component meta file name
 const META_FILE_NAME = 'meta.js'
@@ -719,6 +720,56 @@ export async function discoverComponents(srcDir, sectionPaths = DEFAULT_SECTION_
   return sections
 }
 
+/**
+ * Say what the derivation added, at the one moment the developer is looking.
+ *
+ * ⭐ This is the whole answer to *"a developer may not realize they have to
+ * declare the service"*. `uniweb doctor` cannot reach that developer — it is
+ * opt-in, and someone who does not know the key exists has no reason to run it.
+ * A build is on the path they already walk.
+ *
+ * ⛔ It reports; it never edits. Writing the names into `package.json` is
+ * `uniweb doctor --fix`, where it is a thing the developer asked for and can
+ * read in a diff — a build that rewrites source on every run is a surprise, and
+ * the artifact is already correct without it.
+ */
+function reportSupports(srcDir, authored, derived, emitted) {
+  if (!derived) return
+
+  const added = (emitted || []).filter((s) => !(authored || []).includes(s))
+
+  if (added.length > 0) {
+    const list = added.join(', ')
+    if (authored === undefined) {
+      console.log(`Derived uniweb.supports from the bundle: ${list}`)
+      console.log(`  Nothing was declared, so this is what the foundation publishes.`)
+      console.log(`  \`uniweb doctor --fix\` writes it into package.json if you want it in the file.`)
+    } else if (authored.length === 0) {
+      // An explicit `[]` says "this foundation honours no host service", and the
+      // bundle contradicts it. The union wins — evidence beats a stale claim —
+      // but silently overriding what someone typed is how a declaration stops
+      // meaning anything, so say it.
+      console.warn(
+        `Warning: ${srcDir}/package.json declares \`uniweb.supports: []\` (no services), ` +
+          `but the bundle reaches for ${list}. Publishing ${list}.`,
+      )
+    } else {
+      console.log(`Derived uniweb.supports additions: ${list} (declared: ${authored.join(', ')})`)
+    }
+  }
+
+  if (derived.blind && (emitted === undefined || emitted.length === 0)) {
+    // The one case where an empty result is NOT a proven "none": something
+    // named a service in a way the AST could not read, so the set is short by
+    // an unknown amount and absent/UNKNOWN is the honest wire value.
+    console.warn(
+      `Warning: a service is resolved by a computed name, so \`uniweb.supports\` cannot be ` +
+        `derived and is left undeclared. List it in package.json to publish it.`,
+    )
+    for (const at of derived.blindAt || []) console.warn(`  at ${at}`)
+  }
+}
+
 /**
  * Build complete schema for a foundation
  * Returns { _self: { identity + config }, ComponentName: componentMeta, ... }
@@ -729,8 +780,11 @@ export async function discoverComponents(srcDir, sectionPaths = DEFAULT_SECTION_
  *
  * @param {string} srcDir - Source directory
  * @param {string[]} [sectionPaths] - Paths to scan for section types
+ * @param {{services: string[], blind: boolean}} [derivedSupports] - what the
+ *   module graph says this foundation reaches for (`foundation/derive-supports.js`).
+ *   Omitted on a dev rebuild, where nothing reads the result.
  */
-export async function buildSchema(srcDir, sectionPaths) {
+export async function buildSchema(srcDir, sectionPaths, derivedSupports = null) {
   // Load identity from package.json
   const identity = await loadPackageJson(srcDir)
 
@@ -763,10 +817,19 @@ export async function buildSchema(srcDir, sectionPaths) {
   // Build _self, stripping the raw extension boolean in favor of normalized role
   const { extension: _ext, ...configWithoutExtension } = foundationConfig
 
+  // `supports` is the one identity field the graph knows better than the file.
+  // `identity.supports` is already normalized (absent stays absent, `[]` stays
+  // `[]`), and composeSupports keeps that three-state distinction while adding
+  // what the bundle proves — see its table. Spread AFTER `...identity` so it
+  // replaces the authored-only value rather than being overwritten by it.
+  const supports = composeSupports(identity.supports, derivedSupports)
+  reportSupports(srcDir, identity.supports, derivedSupports, supports.supports)
+
   return {
     _self: {
       ...configWithoutExtension,
       ...identity,
+      ...supports,
       // foundation.js overrides package.json for editor-facing identity
       ...(foundationConfig.name && { name: foundationConfig.name }),
       ...(foundationConfig.description && { description: foundationConfig.description }),

package/src/site/split-content.js

@@ -2,7 +2,8 @@
  * Split Content Helper
  *
  * Shared utility to determine whether a site should use split page content.
- * Used by the site plugin, prerender, and unicloud.
+ * Used by the site plugin, prerender, and any host that assembles the shell
+ * server-side.
  *
  * @module @uniweb/build/site
  */

package/src/vite-foundation-plugin.js

@@ -15,12 +15,13 @@ import { generateEntryPoint, shouldRegenerateForFile } from './generate-entry.js
 import { processAllPreviews } from './images.js'
 import { generateFoundationVars } from './theme/index.js'
 import { DEFAULT_EXTERNALS } from './import-map-plugin.js'
+import { deriveSupports } from './foundation/derive-supports.js'
 
 /**
  * Build schema.json with preview image references
  */
-async function buildSchemaWithPreviews(srcDir, outDir, isProduction, sectionPaths) {
-  const schema = await buildSchema(srcDir, sectionPaths)
+async function buildSchemaWithPreviews(srcDir, outDir, isProduction, sectionPaths, derivedSupports) {
+  const schema = await buildSchema(srcDir, sectionPaths, derivedSupports)
 
   // Process preview images
   const { schema: schemaWithImages, totalImages } = await processAllPreviews(
@@ -419,20 +420,24 @@ async function emitFoundationVarsCss(outDir, schema) {
  * foundation rebuild. "Same set" was a comment three copies made a promise
  * rather than a fact; deriving it makes drift unrepresentable.
  *
- * PLUS the client-only libraries kit code-splits via dynamic import:
+ * PLUS the client-only library kit code-splits via dynamic import:
  *   - shiki / shiki/bundle/full — syntax highlighting (kit Code renderer)
- *   - fuse.js                   — client search index
- * Both hydrate in the browser and never run during renderToString (CLAUDE.md
- * gotcha #12). Keeping them external drops the ~10 MB Shiki language graph from
- * the SSR bundle and leaves them as DORMANT dynamic imports the isolate never
- * awaits — so no extra modules-map entry is needed for them edge-side.
+ * It hydrates in the browser and never runs during renderToString (CLAUDE.md
+ * gotcha #12). Keeping it external drops the ~10 MB Shiki language graph from
+ * the SSR bundle and leaves it a DORMANT dynamic import the isolate never
+ * awaits — so no extra modules-map entry is needed for it edge-side.
+ *
+ * ⛔ `fuse.js` was listed here too, until the local search ranker became
+ * `@uniweb/projections/search` (2026-09-06). Nothing imports fuse now, so the
+ * entry matched no id and was removed rather than left as a claim that it is
+ * still in play. The projections engine needs no entry: it is a leaf of a
+ * package already in the graph, not a third-party dependency.
  */
 const SSR_DEFAULT_EXTERNALS = DEFAULT_EXTERNALS
 
 function isSSRExternal(id) {
   if (SSR_DEFAULT_EXTERNALS.includes(id)) return true
   if (id === 'shiki' || id.startsWith('shiki/')) return true
-  if (id === 'fuse.js' || id.startsWith('fuse.js/')) return true
   return false
 }
 
@@ -442,11 +447,11 @@ function isSSRExternal(id) {
  *
  * The modern browser `entry.js` is a facade that re-exports from
  * `_entry.generated-*.js` and lazily code-splits kit's client-only features
- * (Shiki, Fuse) into hundreds of chunks — a graph the Cloudflare Dynamic Worker
+ * (Shiki) into hundreds of chunks — a graph the Cloudflare Dynamic Worker
  * isolate can't resolve (it loads a single `foundation` module). This builds the
  * SAME source entry into ONE file, inlining the foundation's own graph and
  * externalizing the runtime/React set (→ the isolate's shared worker-runtime)
- * and the client-only Shiki/Fuse libs. Result: a ~foundation-sized ESM module
+ * and the client-only Shiki lib. Result: a ~foundation-sized ESM module
  * (no React, no Shiki) the edge loads as `foundation` for request-time SSR.
  *
  * Built from source (not by re-bundling the built `entry.js`, whose Shiki
@@ -583,10 +588,23 @@ export function foundationBuildPlugin(options = {}) {
       isDevRebuild = (config.plugins || []).some((p) => p?.name === DEV_REBUILD_MARKER)
     },
 
-    async writeBundle() {
+    async writeBundle(_options, bundle) {
       // Skip if this is a recursive call from buildSSRBundle
       if (_buildingSSRBundle) return
 
+      // What host services this foundation actually reaches for, read off the
+      // post-tree-shake module graph rather than asked for in package.json.
+      //
+      // ⛔ GATED ON `isDevRebuild`, NOT ON `isProduction` — the dev server runs
+      // a real Vite build() of the foundation on every watched change, so
+      // `command`, `mode` and `isProduction` all say "build" and cannot tell a
+      // save from a shipping build (see DEV_REBUILD_MARKER). Same gate, and the
+      // same reason, as the entry-ssr.js sub-build below: nothing in the dev
+      // loop reads this, because `supports` is register-time metadata and dev
+      // never registers. `register`'s build-if-stale check treats a dist left
+      // by a dev session as stale, so this can never ship underived.
+      const derivedSupports = isDevRebuild ? null : deriveSupports(bundle, this)
+
       // After bundle is written, generate schema.json in meta folder
       const outDir = resolve(resolvedOutDir)
       const metaDir = join(outDir, 'meta')
@@ -598,7 +616,8 @@ export function foundationBuildPlugin(options = {}) {
         resolvedSrcDir,
         outDir,
         isProduction,
-        sectionPaths
+        sectionPaths,
+        derivedSupports
       )
 
       const schemaPath = join(metaDir, 'schema.json')
@@ -627,7 +646,7 @@ export function foundationBuildPlugin(options = {}) {
       // browser dist/entry.js — for the Cloudflare edge isolate. React + the
       // runtime stay externalized (resolved to the isolate's SHARED
       // worker-runtime, so runtime patches propagate without a rebuild — the
-      // Strategy S win); the client-only Shiki/Fuse libs are externalized so the
+      // Strategy S win); the client-only Shiki lib are externalized so the
       // ~10 MB Shiki graph stays out. The edge loads this as its single
       // `foundation` module for request-time SSR, gated on its presence.
       //
@@ -721,8 +740,14 @@ export function foundationPlugin(options = {}) {
       devPlugin.configResolved?.(config)
     },
 
+    // ⛔ `.call(this, …)`, not `buildPlugin.writeBundle(…)`. The inner hook reads
+    // the Rollup plugin context (`this.getModuleInfo`) to derive
+    // `uniweb.supports` from the module graph, and a plain method call would
+    // bind `this` to `buildPlugin` instead. Nothing would throw: the context
+    // probe is optional-chained, so the derivation would silently return an
+    // empty set and every foundation would publish nothing.
     async writeBundle(...args) {
-      await buildPlugin.writeBundle?.(...args)
+      await buildPlugin.writeBundle?.call(this, ...args)
     },
 
     handleHotUpdate(...args) {