@uniweb/kit 0.13.4 → 0.13.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/kit",
-  "version": "0.13.4",
+  "version": "0.13.6",
   "description": "Standard component library for Uniweb foundations",
   "type": "module",
   "exports": {
@@ -44,8 +44,8 @@
     "shiki": "^3.0.0",
     "tailwind-merge": "^3.6.0",
     "temml": "^0.13.2",
-    "@uniweb/core": "^0.11.3",
-    "@uniweb/semantic-parser": "^1.3.0",
+    "@uniweb/semantic-parser": "^1.3.1",
+    "@uniweb/core": "^0.12.1",
     "@uniweb/scene": "^0.1.3"
   },
   "peerDependencies": {

package/src/search/client.js

@@ -10,12 +10,28 @@
  *
  * Resolution order:
  *   1. `site.yml  search.provider`  — the author's explicit choice
- *   2. `'index'`                    — the free default, works on any host
+ *   2. the HOST's offer             — `config.services.search` in the payload,
+ *                                     read through `resolveService` → `endpoint`
+ *   3. `'index'`                    — the free default, works on any host
  *
- * A future tier sits between them: a host that serves search declaring it in
- * the payload it already sends, the way `config.base` already tells the runtime
- * where the site is being served from. That wire key is the host's to specify,
- * so it is deliberately not invented here.
+ * ⛔ Tier 2 SHIPPED. This block described it as "a future tier … deliberately
+ * not invented here" until 2026-08-25, while `resolveService` was imported at
+ * the top of this file and read ~100 lines below. The wire key is
+ * `config.services.search`, resolved by `@uniweb/core/services` on the same
+ * two-tier rule every site service uses (site-authored wins, host fills gaps).
+ *
+ * ⚠️ That stale sentence had a cost outside this repo. The hosting lane could
+ * not tell from reading whether kit consumed the block, asked in a collab
+ * channel, and the answer mattered: on the sync/link lane the framework emits
+ * NO search index at all (removed 2026-08-01, `@uniweb/build`
+ * `site/build-site-data.js`), so tier 3 requests a `search-index.json` that
+ * nothing on that lane writes. A reader of this comment concluded the host tier
+ * did not exist and the block was decoration; both halves were wrong.
+ *
+ * ⭐ So tier 3 is "the free default" only where something EMITS the index —
+ * the bundle lane and any static host. It is not a universal fallback, and a
+ * host that answers search at its own address must be declared for kit to
+ * reach it.
  *
  * Provider contract (duck-typed, matching how the FetcherDispatcher treats
  * transports):
@@ -126,9 +142,69 @@ export function createSearchClient(website, options = {}) {
   // host serves none.
   const authoredProvider = website?.config?.search?.provider
 
+  // ⛔ …BUT AN AUTHORED `index` IS NOT A CHOICE, IT IS THE DEFAULT SPELLED OUT.
+  // `getSearchConfig()` fills `provider: 'index'` when the author said nothing,
+  // and `docs/authoring/search.md` shows it in its options block labelled
+  // "default" — so a site that copied that block to set `include:` or
+  // `exclude:` carries it without having decided anything.
+  //
+  // Treating it as a veto pinned exactly those sites to the local index. On a
+  // host-served site that index does not exist (the build stops emitting one on
+  // that lane), so an ENTITLED site — one whose host does offer search — drew a
+  // box, queried `search-index.json`, and got a 404. They had bought the
+  // feature and could not use it.
+  //
+  // ⇒ An authored `index` no longer outranks a host's offer. Any OTHER authored
+  // provider still does: `endpoint` and a foundation transport are real choices
+  // and the comment above still applies to them.
+  //
+  // ⚠️ This removes one thing an author could previously express — "use the
+  // local index even though my host offers search". On a host-served lane that
+  // preference resolves to a 404 either way, and on a static host `source` is
+  // never 'host' so this branch cannot fire and the local index is untouched.
+  //
+  // ⛔ REACHES NEW AND REBUILT FOUNDATIONS ONLY. A foundation bundles its own
+  // frozen copy of this file, so an already-published one keeps the old
+  // precedence. Unlike the host-decline check — which lives in `@uniweb/core`
+  // precisely so the runtime carries it to every foundation regardless of age —
+  // provider selection is kit's, and frozen kit reads `website.config` directly.
+  // There is no honest core-side fix: it would mean rewriting authored config
+  // to steer a consumer's branch.
+  const authoredVeto =
+    authoredProvider && authoredProvider !== 'index' ? authoredProvider : null
+
+  // ⛔ THE HOST ANSWERED AND DECLINED. `resolveService` returns
+  // `{ url: null, source: 'host' }` when a host declares the service NAME
+  // while offering no address — the decline shape `@uniweb/core/services`
+  // documents ("absence is a behavioural decision rather than a message").
+  //
+  // Falling through to `'index'` here would be wrong twice: the host has said
+  // it does not serve search, and on a host-served lane the framework emits no
+  // index to fall back to, so the fallback resolves to a 404. Draw nothing
+  // instead — `isEnabled()` reports false and `query()` returns empty without
+  // a request.
+  //
+  // ⚠️ Only a DECLINE does this. `source: null` — nobody declared the service
+  // at all — still means `'index'`, which is correct and is the static-host
+  // path: there the build DOES emit the index.
+  //
+  // ⛔ DO NOT ADD A FALLBACK THAT FIRES ON THIS SHAPE. The contract, settled
+  // with a host implementation 2026-08-25: **a host that OFFERS a service must
+  // declare it WITH an address** — offered is `{endpoint}`, declined is `{}`.
+  // Routing `{}` to `endpoint-provider`'s `DEFAULT_ENDPOINT` looks like a free
+  // saving and makes an offered service indistinguishable from a declined one:
+  // no search box, no error, nothing to grep for.
+  //
+  // ⭐ A site's OWN declaration still wins — `resolveService` answers tier 1
+  // with `source: 'site'`, so an operator running self-hosted search on a host
+  // that does not sell it is untouched. Pinned in
+  // `tests/search-host-decline.test.js`; that is the case worth re-running if
+  // this branch is ever edited, because the headline case never breaks.
+  const hostDeclined = service.source === 'host' && !service.url
+
   const declared =
     providerOverride ||
-    authoredProvider ||
+    authoredVeto ||
     (service.source === 'host' ? 'endpoint' : 'index')
 
   // One in-flight resolution shared by every caller.
@@ -193,11 +269,21 @@ export function createSearchClient(website, options = {}) {
 
   return {
     /**
-     * Check if search is enabled
+     * Check if search is enabled.
+     *
+     * Two independent ways it is off, and a caller needs neither to tell them
+     * apart: the SITE disabled it (`search: false` / `search: { enabled:
+     * false }`), or the HOST declared the service and offered no address —
+     * see `hostDeclined` above. Either way a foundation draws no search UI.
+     *
+     * ⛔ Deliberately no reason string. Which services a site is provisioned
+     * for is not a visitor's business and could not be localized from a public
+     * package anyway — the rule `@uniweb/core/services` states at length.
+     *
      * @returns {boolean}
      */
     isEnabled() {
-      return website.isSearchEnabled()
+      return website.isSearchEnabled() && !hostDeclined
     },
 
     /**
@@ -273,6 +359,13 @@ export function createSearchClient(website, options = {}) {
         return { results: [], total: 0 }
       }
 
+      // The host declared the service and offered no address. Return empty
+      // rather than requesting anything — the alternative is a fetch we
+      // already know the answer to. Silent: a foundation that checked
+      // `isEnabled()` never reaches this, and one that did not should not fill
+      // a visitor's console over a service the site was never provisioned for.
+      if (hostDeclined) return { results: [], total: 0 }
+
       const opts = { limit, type, route, signal }
 
       try {

package/src/search/providers/endpoint-provider.js

@@ -16,7 +16,29 @@
 import { emptyResult } from './result.js'
 import { resolveServiceUrl } from '../../utils/services.js'
 
-/** Path used when a site declares `provider: endpoint` without an `endpoint:`. */
+/**
+ * Path used when a site declares `provider: endpoint` without an `endpoint:`.
+ *
+ * ⛔ THIS COVERS THE AUTHORED TIER ONLY — it is unreachable for a HOST-declared
+ * service, and it must stay that way.
+ *
+ * A host that declares the service name while offering no address is a
+ * **decline** (`@uniweb/core/services`), and `client.js` short-circuits on it
+ * before any provider is selected. So `{ "search": {} }` from a host means
+ * "draw nothing", never "use the default".
+ *
+ * ⇒ **The contract, settled with a host implementation 2026-08-25: a host that
+ * OFFERS a service must declare it WITH an address.** Offered is `{endpoint}`;
+ * declined is `{}`. The two are one byte apart and the failure is silent — an
+ * entitled site drawing no search box.
+ *
+ * ⚠️ **The saving that looks available from either side, and is not.** From
+ * here: *"a host need not send an address, kit defaults to `_search` anyway."*
+ * From the emitter: *"why emit `/_search` when kit defaults to it?"* **Both
+ * collapse the two states into one.** It was proposed and withdrawn the day
+ * this was written, by the lane that had just shipped the decline branch — the
+ * hazard does not look like a hazard while you are authoring it.
+ */
 const DEFAULT_ENDPOINT = '_search'
 
 /**
@@ -126,27 +148,52 @@ export function createEndpointProvider(website, options = {}) {
       })
 
       if (!response.ok) {
-        // An endpoint that declines usually explains why, in words meant for a
-        // visitor rather than a status code — "Search is not available on this
-        // site." Read it and carry it, the same way `submitForm` does with a
-        // rejected submission.
+        // ⛔ A HOST'S DECLINE TEXT IS A DIAGNOSTIC, NEVER VISITOR COPY.
         //
-        // This does not change the degradation: a failed search still falls
-        // back to the local index, because a failed READ should degrade and
-        // that guarantee is older than this. What changes is that when there is
-        // no index to fall back to, the error a foundation can surface says
-        // something a person understands instead of a number.
+        // This block used to argue the opposite — that an endpoint "explains
+        // why, in words meant for a visitor", so kit should carry that sentence
+        // up for a foundation to render. That is wrong, and it was ruled
+        // against on 2026-08-25: a control for a service the site does not have
+        // must not be DRAWN in the first place, so there is no place for an
+        // apology and nothing for a visitor to read. A site with no search is
+        // not broken; it simply has no search, the same way it has no contact
+        // form when submissions are not enabled.
+        //
+        // Two reasons it cannot be visitor copy even if one wanted it to be:
+        // it reports the operator's provisioning state to the public, and it
+        // arrives in one language from a service layer, bypassing the site's
+        // localization entirely. Any text a visitor reads is site content.
+        //
+        // ⇒ The message is kept because a developer reading a console needs
+        // more than "403". `isEnabled()` is what a foundation asks, and it is
+        // false long before this line runs.
+        //
+        // ⛔ THE HOST'S SENTENCE GOES TO THE CONSOLE, NEVER INTO THE THROW.
+        //
+        // It used to become the Error's message, and `useSearch` exposes
+        // `error` — so a foundation rendering it would have shown a visitor a
+        // host-authored English sentence about someone's provisioning state.
+        // The only thing preventing that was `client.js`'s local-index
+        // fallback swallowing the throw, which is incidental: that fallback
+        // exists to DEGRADE, and removing it (reasonable — on a host-served
+        // lane there is no index to fall back to) would have surfaced the
+        // sentence as its first act.
+        //
+        // ⇒ Splitting the two registers removes the ordering hazard entirely
+        // rather than documenting it: whatever reaches `error` is now
+        // framework-authored and carries no host prose, so the fallback can be
+        // removed on its own merits whenever someone wants to.
         let declined
         try {
           declined = (await response.json())?.error
         } catch {
           /* not JSON — the status is all there is */
         }
-        throw new Error(
-          typeof declined === 'string' && declined.trim()
-            ? declined.trim()
-            : `Search endpoint returned ${response.status}`
-        )
+        if (typeof declined === 'string' && declined.trim()) {
+          // Developer register: a console reader needs more than a number.
+          console.warn(`[uniweb] search endpoint declined: ${declined.trim()}`)
+        }
+        throw new Error(`Search endpoint returned ${response.status}`)
       }
 
       const payload = await response.json()