@uniweb/runtime 0.8.0 → 0.8.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/runtime",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "description": "Minimal runtime for loading Uniweb foundations",
   "type": "module",
   "exports": {
@@ -8,7 +8,8 @@
     "./ssr": "./dist/ssr.js",
     "./provider": "./src/RuntimeProvider.jsx",
     "./setup": "./src/setup.js",
-    "./foundation-loader": "./src/foundation-loader.js"
+    "./foundation-loader": "./src/foundation-loader.js",
+    "./default-fetcher": "./src/default-fetcher.js"
   },
   "files": [
     "src",
@@ -34,14 +35,14 @@
     "node": ">=20.19"
   },
   "dependencies": {
-    "@uniweb/core": "0.7.0",
+    "@uniweb/core": "0.7.1",
     "@uniweb/theming": "0.1.3"
   },
   "devDependencies": {
     "@vitejs/plugin-react": "^4.5.2",
     "vite": "^7.3.1",
     "vitest": "^2.0.0",
-    "@uniweb/build": "0.9.5"
+    "@uniweb/build": "0.10.1"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",

package/src/default-fetcher.js

@@ -28,19 +28,19 @@
  * Every key is optional. When the config is empty, behavior is byte-for-byte
  * identical to a plain `fetch()` with JSON parsing.
  *
- * Not exported from @uniweb/runtime's public surface: foundations never
- * need to reach for this. If a foundation wants to compose the default
- * behavior with middleware, its choices are:
+ * Exported from a subpath — `@uniweb/runtime/default-fetcher` — for
+ * runtime-level callers (the editor's preview iframe, custom runtime
+ * harnesses). **Foundations should not import this.** A foundation that
+ * wants plain URL + JSON behavior simply omits its own fetcher; the
+ * runtime installs this one automatically. A foundation that needs
+ * auth / retry / response normalization declares a named transport
+ * and composes `@uniweb/fetchers` middleware around its own `resolve()`.
  *
- *   - Don't declare a fetcher. The runtime's default already handles
- *     plain URL + JSON responses (and the site-level vocabulary).
- *   - Declare a custom fetcher and write its own `fetch()` call. When it
- *     needs auth / retry / response normalization, compose @uniweb/fetchers
- *     primitives around its own resolve function.
- *
- * There is intentionally no "reuse the default and wrap it" path — doing
- * so would duplicate this code into every foundation bundle. Custom
- * fetchers own their transport; the default exists for sites without one.
+ * There is intentionally no "reuse the default and wrap it" path for
+ * foundations — doing so would duplicate this code into every foundation
+ * bundle. The subpath export exists specifically for preview-mode shells
+ * that need to delegate *non-authenticated* requests to a default-fetcher
+ * instance while intercepting authenticated ones via their own transport.
  *
  * Intentional omissions: credentials / secrets are NOT part of the vocabulary.
  * Any value the framework puts into the served HTML is public to the browser.
@@ -56,7 +56,17 @@
  * it's public. That's not a framework feature gap; it's how browsers work.
  */
 
-import { substitutePlaceholders, matchWhere, deriveCacheKey } from '@uniweb/core'
+import {
+  substitutePlaceholders,
+  matchWhere,
+  deriveCacheKey,
+  resolveRequestStyle,
+} from '@uniweb/core'
+
+// Phase 2 of the request-styles landing will read `config.request.style`
+// and dispatch through the registry; in Phase 1 we hard-wire the ambient
+// default (json-body) via the same resolver. No behavior change — the
+// resolved style is json-body, which encodes today's conventions.
 
 // Operators the default fetcher knows how to handle. When listed in
 // `config.supports`, they're shipped to the source as part of the
@@ -71,12 +81,15 @@ const KNOWN_OPERATORS = new Set(['where', 'limit', 'sort'])
  *   for subpath deployments. Remote URLs pass through unchanged.
  * @param {Object} [options.config={}] - Site-level fetcher config from
  *   `site.yml fetcher:`. Vocabulary recognized by the default fetcher:
- *   `baseUrl`, `headers`, `envelope`. Unknown keys are ignored (foundations
- *   may use the same block for their own keys).
- *   Default behavior (empty config) matches today's plain GET + JSON.
+ *   `baseUrl`, `headers`, `envelope`, `supports`, `request.style`,
+ *   `request.rename`. Unknown keys are ignored (foundations may use the
+ *   same block for their own keys). Default behavior (empty config)
+ *   matches today's plain GET + JSON.
+ * @param {boolean} [options.dev=false] - Enable dev-mode warnings (unknown
+ *   style name, unknown rename operator).
  * @returns {{ resolve: (req: Object, ctx: Object) => Promise<{ data, error? }> }}
  */
-export function createDefaultFetcher({ basePath = '', config = {} } = {}) {
+export function createDefaultFetcher({ basePath = '', config = {}, dev = false } = {}) {
   const pathPrefix = basePath && basePath !== '/' ? basePath.replace(/\/$/, '') : ''
 
   const baseUrl = typeof config?.baseUrl === 'string'
@@ -87,6 +100,25 @@ export function createDefaultFetcher({ basePath = '', config = {} } = {}) {
   // requests are never decorated — they're just file reads under public/.
   const staticHeaders = buildStaticHeaders(config?.headers)
 
+  // `supports:` declares which query operators (where, limit, sort) the
+  // backend evaluates at the source. Operators in this list are shipped
+  // in the request; operators not in this list are applied as a JS
+  // fallback after the response arrives. Default: empty — the framework
+  // default fetcher serving static files supports nothing natively.
+  const supports = normalizeSupports(config?.supports)
+
+  // Request style — how operators get reshaped for the wire. Selected
+  // by name via `site.yml fetcher.request.style`; `null`/absent resolves
+  // to the ambient default (json-body).
+  const requestConfig = (config?.request && typeof config.request === 'object') ? config.request : {}
+  const styleName = typeof requestConfig.style === 'string' ? requestConfig.style : null
+  const style = resolveRequestStyle(styleName, { dev })
+
+  // Operator-name renames applied on top of the style's wire names.
+  // Shallow: only the operator keys (where / limit / sort) are rewritten.
+  // Field names inside a where-object are untouched.
+  const rename = normalizeRename(requestConfig.rename, style, { dev })
+
   // `envelope:` extends today's `transform:` to cover detail responses and
   // errors. Three dot-paths, all optional:
   //   - envelope.collection — applied on collection responses. Per-fetch
@@ -94,16 +126,15 @@ export function createDefaultFetcher({ basePath = '', config = {} } = {}) {
   //   - envelope.item       — applied when request.dynamicContext is set
   //     (the request is for a template-page item).
   //   - envelope.error      — extract error text from non-2xx response body.
-  const envelope = (config?.envelope && typeof config.envelope === 'object')
+  //
+  // Priority (highest wins): per-fetch request.envelope > site-level
+  // config.envelope > style.defaultEnvelope. A style that defaults an
+  // envelope (e.g. Strapi's `{ data }` wrapper) still defers to any
+  // explicit site-level override.
+  const siteEnvelope = (config?.envelope && typeof config.envelope === 'object')
     ? config.envelope
-    : {}
-
-  // `supports:` declares which query operators (where, limit, sort) the
-  // backend evaluates at the source. Operators in this list are shipped
-  // in the request; operators not in this list are applied as a JS
-  // fallback after the response arrives. Default: empty — the framework
-  // default fetcher serving static files supports nothing natively.
-  const supports = normalizeSupports(config?.supports)
+    : null
+  const envelope = { ...(style.defaultEnvelope || {}), ...(siteEnvelope || {}) }
 
   return {
     /**
@@ -119,15 +150,24 @@ export function createDefaultFetcher({ basePath = '', config = {} } = {}) {
      * the predicate travels in the request.
      */
     cacheKey(request) {
-      // Build a request projection that includes only pushed-down operators.
-      // deriveCacheKey already covers the always-keyed fields.
+      // Build a request projection that includes only operators the active
+      // style will actually push for this request. deriveCacheKey already
+      // covers the always-keyed fields.
+      //
+      // The key also includes the style name — two sites with different
+      // styles against the same URL produce different wire requests, so
+      // their responses must not alias.
       const base = deriveCacheKey(request)
       const projected = {}
       for (const op of supports) {
+        if (!style.canPush.has(op)) continue
         if (request[op] !== undefined) projected[op] = request[op]
       }
-      if (Object.keys(projected).length === 0) return base
-      return base + '::' + JSON.stringify(projected)
+      if (Object.keys(projected).length === 0 && style.name === 'json-body') {
+        // Keep back-compat key shape when the ambient default pushes nothing.
+        return base
+      }
+      return base + '::style=' + style.name + '::' + JSON.stringify(projected)
     },
 
     async resolve(request, ctx = {}) {
@@ -167,25 +207,37 @@ export function createDefaultFetcher({ basePath = '', config = {} } = {}) {
       // decorate local file reads with tenant/content-type headers.
       if (isRemote && staticHeaders) Object.assign(headers, staticHeaders)
 
-      // Push down supported query operators to the source. Pushdown only
-      // applies to remote URLs — local `path:` reads are static files that
-      // can't filter or sort. Operators not pushed down get applied as a
-      // JS fallback after the response (see post-fetch block below).
+      // Push down supported query operators to the source via the active
+      // request style. Pushdown only applies to remote URLs — local `path:`
+      // reads are static files that can't filter or sort. Operators the
+      // style didn't push get applied as a JS fallback after the response
+      // (see the post-fetch block below).
       //
-      // GET pushdown uses URL query parameters: `?_where=<JSON>`, `?_limit=`,
-      // `?_sort=field:dir`. The leading underscore avoids collision with
-      // backend-specific params. POST pushdown injects supported operators
-      // into the request body alongside any author-supplied body.
-      let pushedOperators = new Set()
+      // The style owns the wire format. Today's json-body style encodes
+      // GET pushdown as `?_where=<JSON>&_limit=&_sort=` and POST pushdown
+      // as top-level keys merged into an object body. Other styles
+      // (flat-query, strapi) will ship in Phase 3.
+      const pushCandidates = new Set()
       if (isRemote) {
         for (const op of KNOWN_OPERATORS) {
-          if (supports.has(op) && request[op] !== undefined && request[op] !== null) {
-            pushedOperators.add(op)
+          if (
+            supports.has(op) &&
+            style.canPush.has(op) &&
+            request[op] !== undefined &&
+            request[op] !== null
+          ) {
+            pushCandidates.add(op)
           }
         }
       }
-      if (pushedOperators.size > 0 && method === 'GET') {
-        target = appendQueryParams(target, pushedOperators, request)
+
+      const encoded = pushCandidates.size > 0
+        ? style.encode(request, { method, pushCandidates, rename })
+        : { queryParams: [], bodyMerge: null, pushed: new Set() }
+      const pushedOperators = encoded.pushed
+
+      if (encoded.queryParams.length > 0 && method === 'GET') {
+        target = appendStyleQueryParams(target, encoded.queryParams)
       }
 
       if (method === 'POST') {
@@ -199,9 +251,9 @@ export function createDefaultFetcher({ basePath = '', config = {} } = {}) {
           : rawBody
 
         // Compose the final body: author-supplied body merged with pushed
-        // operators (where/limit/sort). When no body and no pushdown, send
-        // a body containing just the operators if any exist.
-        const finalBody = composePostBody(resolvedBody, pushedOperators, request)
+        // operators from the style. When no body and no pushdown, send
+        // a body containing just the pushed operators if any exist.
+        const finalBody = composePostBody(resolvedBody, encoded.bodyMerge)
 
         if (finalBody !== null) {
           // Default Content-Type to JSON unless the site's static headers
@@ -293,6 +345,31 @@ export function createDefaultFetcher({ basePath = '', config = {} } = {}) {
   }
 }
 
+/**
+ * Normalize the `request.rename` map. Returns null if nothing valid.
+ * Dev-mode warns on operator names that don't exist in the style's
+ * `canPush` set — a rename that targets an operator the style doesn't
+ * push is silently dead config, and the warning surfaces the mistake.
+ */
+function normalizeRename(raw, style, { dev }) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null
+  const out = {}
+  for (const [op, wireName] of Object.entries(raw)) {
+    if (typeof wireName !== 'string' || wireName.length === 0) continue
+    if (dev && !style.canPush.has(op) && !warnedRenameTargets.has(op)) {
+      warnedRenameTargets.add(op)
+      console.warn(
+        `[default-fetcher] request.rename: operator "${op}" is not pushed by ` +
+          `style "${style.name}" — rename has no effect. Known operators for ` +
+          `this style: ${[...style.canPush].join(', ') || '(none)'}.`,
+      )
+    }
+    out[op] = wireName
+  }
+  return Object.keys(out).length ? out : null
+}
+const warnedRenameTargets = new Set()
+
 /**
  * Normalize the supports declaration to a Set of known operators. Unknown
  * operator names are ignored with a one-time dev warning.
@@ -313,58 +390,36 @@ function normalizeSupports(raw) {
 const warnedUnknownOperators = new Set()
 
 /**
- * Append pushed-down operators to a URL as query parameters. Existing
- * query string is preserved.
- *
- * Conventions:
- *   - where:  `?_where=<JSON.stringify(whereObject)>` (URL-encoded)
- *   - limit:  `?_limit=N`
- *   - sort:   `?_sort=field:dir` (matches the author-facing string form)
- *
- * The leading underscore avoids collision with backend-specific params
- * the author may have included in `url:`.
+ * Append [key, value] pairs emitted by a style to a URL as query
+ * parameters. Existing query string is preserved; values are URL-encoded.
  */
-function appendQueryParams(url, pushedOperators, request) {
-  const params = []
-  if (pushedOperators.has('where')) {
-    params.push('_where=' + encodeURIComponent(JSON.stringify(request.where)))
-  }
-  if (pushedOperators.has('limit')) {
-    params.push('_limit=' + encodeURIComponent(String(request.limit)))
-  }
-  if (pushedOperators.has('sort')) {
-    params.push('_sort=' + encodeURIComponent(String(request.sort)))
-  }
-  if (params.length === 0) return url
+function appendStyleQueryParams(url, pairs) {
+  if (!pairs || pairs.length === 0) return url
+  const params = pairs.map(
+    ([k, v]) => encodeURIComponent(k) + '=' + encodeURIComponent(v),
+  )
   const sep = url.includes('?') ? '&' : '?'
   return url + sep + params.join('&')
 }
 
 /**
- * Compose a POST body that includes pushed-down operators alongside the
+ * Compose a POST body that includes the style's bodyMerge alongside the
  * author-supplied body. When neither exists, returns null (no body sent).
  *
- * If the author supplied a body (typically an object for GraphQL or a
- * search endpoint), pushed operators are merged into it as top-level keys
- * (`where`, `limit`, `sort`). If the author supplied a string body, we
- * don't try to merge — the string is sent as-is and operators are
- * dropped. This is a known limitation; sites with string POST bodies
- * needing pushdown should write the operators into the body themselves.
+ * If the author supplied a string body (typically GraphQL), we can't
+ * merge — the string is sent as-is and the style's bodyMerge is dropped.
+ * Sites with string POST bodies needing pushdown should write the
+ * operators into the body themselves.
  */
-function composePostBody(authorBody, pushedOperators, request) {
-  if (pushedOperators.size === 0) {
+function composePostBody(authorBody, bodyMerge) {
+  if (!bodyMerge) {
     return authorBody === undefined ? null : authorBody
   }
-  // String body — can't merge structured operators in.
   if (typeof authorBody === 'string') {
     return authorBody
   }
-  // No body or object body — merge operators.
-  const merged = (authorBody && typeof authorBody === 'object') ? { ...authorBody } : {}
-  if (pushedOperators.has('where')) merged.where = request.where
-  if (pushedOperators.has('limit')) merged.limit = request.limit
-  if (pushedOperators.has('sort')) merged.sort = request.sort
-  return merged
+  const base = (authorBody && typeof authorBody === 'object') ? authorBody : {}
+  return { ...base, ...bodyMerge }
 }
 
 /**

package/src/setup.js

@@ -217,7 +217,8 @@ function buildDefaultFetcher(content) {
   // recognizes `baseUrl` and `envelope`; foundations with their own fetchers
   // may read additional keys from the same block via ctx.website.config.fetcher.
   const config = content?.config?.fetcher ?? {}
-  return createDefaultFetcher({ basePath, config })
+  const dev = !!(import.meta.env && import.meta.env.DEV)
+  return createDefaultFetcher({ basePath, config, dev })
 }
 
 /**