@uniweb/build 0.9.4 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.9.4",
+  "version": "0.10.0",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -54,8 +54,8 @@
     "@uniweb/theming": "0.1.3"
   },
   "optionalDependencies": {
-    "@uniweb/runtime": "0.7.4",
     "@uniweb/content-reader": "1.1.4",
+    "@uniweb/runtime": "0.8.0",
     "@uniweb/schemas": "0.2.1"
   },
   "peerDependencies": {
@@ -65,7 +65,7 @@
     "@tailwindcss/vite": "^4.0.0",
     "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
     "vite-plugin-svgr": "^4.0.0",
-    "@uniweb/core": "0.6.1"
+    "@uniweb/core": "0.7.0"
   },
   "peerDependenciesMeta": {
     "vite": {

package/src/dev-backend.js

@@ -0,0 +1,247 @@
+#!/usr/bin/env node
+/**
+ * Dev backend for testing Uniweb sites with `supports: [where, limit, sort]`.
+ *
+ * Reads a directory of YAML collections (each subfolder is a collection,
+ * each .yml file inside is a record) and exposes them via HTTP. Evaluates
+ * where-objects on the server side using @uniweb/core's matchWhere — the
+ * exact same evaluator the runtime uses as a fallback. This lets you
+ * develop a site against a "real" backend without standing up a database.
+ *
+ * Wire format matches the framework default fetcher's pushdown conventions
+ * (see framework/runtime/src/default-fetcher.js):
+ *
+ *   GET  /api/{collection}                        — full collection
+ *   GET  /api/{collection}?_where=<JSON>          — filtered by where-object
+ *   GET  /api/{collection}?_limit=N               — first N records
+ *   GET  /api/{collection}?_sort=field:dir        — sorted
+ *   POST /api/{collection}  body: { where, ... } — operators in body
+ *   GET  /api/{collection}/{slug}                 — single record
+ *
+ * Usage:
+ *   node scripts/framework/dev-backend.js --collections <path> [--port N]
+ *
+ * Example (academic-metrics):
+ *   node scripts/framework/dev-backend.js \
+ *     --collections framework/templates/academic-metrics/site/collections \
+ *     --port 8080
+ *
+ * Then in the site's site.yml:
+ *   fetcher:
+ *     baseUrl: http://localhost:8080
+ *     supports: [where, limit, sort]
+ *
+ * And rewrite collection refs to URLs, e.g.:
+ *   fetch: { url: /api/members, schema: members }
+ */
+
+import { createServer } from 'node:http'
+import { readFile, readdir, stat } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { resolve, join, basename, extname } from 'node:path'
+import { parseArgs } from 'node:util'
+import yaml from 'js-yaml'
+import { matchWhere } from '@uniweb/core'
+
+const { values } = parseArgs({
+  options: {
+    collections: { type: 'string', short: 'c' },
+    port: { type: 'string', short: 'p', default: '8080' },
+  },
+})
+
+if (!values.collections) {
+  console.error('Usage: dev-backend.js --collections <path> [--port N]')
+  process.exit(1)
+}
+
+const COLLECTIONS_DIR = resolve(values.collections)
+const PORT = Number(values.port)
+
+if (!existsSync(COLLECTIONS_DIR)) {
+  console.error(`Collections directory not found: ${COLLECTIONS_DIR}`)
+  process.exit(1)
+}
+
+// ─── Load collections from disk ─────────────────────────────────────────────
+
+async function loadCollection(dir) {
+  const files = await readdir(dir)
+  const items = []
+  for (const file of files) {
+    const ext = extname(file).toLowerCase()
+    if (!['.yml', '.yaml', '.json'].includes(ext)) continue
+    const filepath = join(dir, file)
+    const content = await readFile(filepath, 'utf8')
+    let data
+    try {
+      data = ext === '.json' ? JSON.parse(content) : yaml.load(content)
+    } catch (err) {
+      console.warn(`[dev-backend] Failed to parse ${filepath}: ${err.message}`)
+      continue
+    }
+    if (data == null) continue
+    const slug = basename(file, ext)
+    if (Array.isArray(data)) {
+      // Array-form file: each element is a record.
+      for (const record of data) {
+        if (record && typeof record === 'object') items.push(record)
+      }
+    } else if (typeof data === 'object') {
+      items.push({ slug, ...data })
+    }
+  }
+  return items
+}
+
+async function loadAllCollections() {
+  const entries = await readdir(COLLECTIONS_DIR)
+  const collections = {}
+  for (const name of entries) {
+    const fullPath = join(COLLECTIONS_DIR, name)
+    const s = await stat(fullPath)
+    if (!s.isDirectory()) continue
+    collections[name] = await loadCollection(fullPath)
+    console.log(`[dev-backend] Loaded ${collections[name].length} items from "${name}"`)
+  }
+  return collections
+}
+
+// ─── Operator handling (mirrors default-fetcher pushdown wire format) ───────
+
+function applyOperators(items, operators) {
+  let result = items
+  if (operators.where) {
+    result = matchWhere(operators.where, result)
+  }
+  if (operators.sort) {
+    result = applySort(result, operators.sort)
+  }
+  if (typeof operators.limit === 'number' && operators.limit > 0) {
+    result = result.slice(0, operators.limit)
+  }
+  return result
+}
+
+function applySort(items, sortExpr) {
+  const sorts = String(sortExpr).split(',').map((s) => {
+    const [field, dir = 'asc'] = s.trim().split(/\s+/)
+    return { field, desc: dir.toLowerCase() === 'desc' }
+  })
+  return [...items].sort((a, b) => {
+    for (const { field, desc } of sorts) {
+      const av = a?.[field] ?? ''
+      const bv = b?.[field] ?? ''
+      if (av < bv) return desc ? 1 : -1
+      if (av > bv) return desc ? -1 : 1
+    }
+    return 0
+  })
+}
+
+function parseOperatorsFromQuery(searchParams) {
+  const out = {}
+  if (searchParams.has('_where')) {
+    try {
+      out.where = JSON.parse(searchParams.get('_where'))
+    } catch (err) {
+      throw new Error(`Invalid _where JSON: ${err.message}`)
+    }
+  }
+  if (searchParams.has('_limit')) {
+    out.limit = Number(searchParams.get('_limit'))
+  }
+  if (searchParams.has('_sort')) {
+    out.sort = searchParams.get('_sort')
+  }
+  return out
+}
+
+async function readJsonBody(req) {
+  return new Promise((resolve, reject) => {
+    let body = ''
+    req.on('data', (chunk) => { body += chunk })
+    req.on('end', () => {
+      if (!body) return resolve({})
+      try { resolve(JSON.parse(body)) }
+      catch (err) { reject(new Error(`Invalid JSON body: ${err.message}`)) }
+    })
+    req.on('error', reject)
+  })
+}
+
+// ─── HTTP server ────────────────────────────────────────────────────────────
+
+function send(res, status, body) {
+  res.writeHead(status, {
+    'Content-Type': 'application/json',
+    'Access-Control-Allow-Origin': '*',
+    'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
+    'Access-Control-Allow-Headers': 'Content-Type',
+  })
+  res.end(typeof body === 'string' ? body : JSON.stringify(body))
+}
+
+async function handleRequest(req, res, collections) {
+  if (req.method === 'OPTIONS') return send(res, 204, '')
+
+  const url = new URL(req.url, `http://${req.headers.host}`)
+  const match = url.pathname.match(/^\/api\/([^/]+)(?:\/([^/]+))?$/)
+  if (!match) return send(res, 404, { error: 'Not found' })
+
+  const [, collectionName, slug] = match
+  const items = collections[collectionName]
+  if (!items) return send(res, 404, { error: `Unknown collection: ${collectionName}` })
+
+  // Single record by slug.
+  if (slug) {
+    const item = items.find((r) => r?.slug === slug)
+    if (!item) return send(res, 404, { error: `No record with slug "${slug}"` })
+    return send(res, 200, item)
+  }
+
+  // Collection — apply operators from query string (GET) or body (POST).
+  let operators
+  try {
+    operators = req.method === 'POST'
+      ? await readJsonBody(req)
+      : parseOperatorsFromQuery(url.searchParams)
+  } catch (err) {
+    return send(res, 400, { error: err.message })
+  }
+
+  let result
+  try {
+    result = applyOperators(items, operators)
+  } catch (err) {
+    return send(res, 400, { error: `Operator evaluation failed: ${err.message}` })
+  }
+  return send(res, 200, result)
+}
+
+// ─── Boot ───────────────────────────────────────────────────────────────────
+
+const collections = await loadAllCollections()
+const knownCollections = Object.keys(collections)
+if (knownCollections.length === 0) {
+  console.warn('[dev-backend] No collections found.')
+}
+
+const server = createServer((req, res) => {
+  handleRequest(req, res, collections).catch((err) => {
+    console.error('[dev-backend] Request handler threw:', err)
+    send(res, 500, { error: 'Internal server error' })
+  })
+})
+
+server.listen(PORT, () => {
+  console.log(`[dev-backend] Listening on http://localhost:${PORT}`)
+  console.log(`[dev-backend] Collections: ${knownCollections.join(', ') || '(none)'}`)
+  console.log('[dev-backend] Endpoints:')
+  for (const name of knownCollections) {
+    console.log(`  GET  /api/${name}                  — full collection`)
+    console.log(`  GET  /api/${name}?_where=<JSON>    — filtered`)
+    console.log(`  GET  /api/${name}/{slug}            — single record`)
+    console.log(`  POST /api/${name}  body: { where } — operators in body`)
+  }
+})

package/src/prerender.js

@@ -11,6 +11,7 @@ import { readFile, writeFile, mkdir } from 'node:fs/promises'
 import { existsSync, readdirSync, statSync } from 'node:fs'
 import { join, dirname, resolve } from 'node:path'
 import { pathToFileURL } from 'node:url'
+import { deriveCacheKey } from '@uniweb/core'
 import { executeFetch, mergeDataIntoContent, singularize } from './site/data-fetcher.js'
 import { shouldSplitContent } from './site/split-content.js'
 
@@ -509,27 +510,19 @@ export async function prerenderSite(siteDir, options = {}) {
     const shellPath = existsSync(htmlPath) ? htmlPath : join(distDir, 'index.html')
     const htmlShell = await readFile(shellPath, 'utf8')
 
-    // Initialize the Uniweb runtime using the shared SSR module
-    const uniweb = initPrerender(siteContent, foundation, { onProgress })
-
-    // Build-specific: pre-populate DataStore so EntityStore can resolve data during prerender
-    if (fetchedData.length > 0 && uniweb.activeWebsite?.dataStore) {
-      for (const entry of fetchedData) {
-        uniweb.activeWebsite.dataStore.set(entry.config, entry.data)
-      }
-    }
-
-    // Build-specific: load extensions (secondary foundations via URL)
-    const extensions = siteContent.config?.extensions
-    if (extensions?.length) {
-      onProgress(`Loading ${extensions.length} extension(s)...`)
+    // Build-specific: load extensions (secondary foundations via URL) BEFORE
+    // initPrerender so the Website's FetcherDispatcher sees their routes.
+    const extensionSources = siteContent.config?.extensions
+    const loadedExtensions = []
+    if (extensionSources?.length) {
+      onProgress(`Loading ${extensionSources.length} extension(s)...`)
       const projectRoot = join(siteDir, '..')
-      for (const ext of extensions) {
+      for (const ext of extensionSources) {
         try {
           const url = typeof ext === 'string' ? ext : ext.url
           const extPath = resolveExtensionPath(url, distDir, projectRoot)
           const extModule = await import(pathToFileURL(extPath).href)
-          uniweb.registerExtension(extModule)
+          loadedExtensions.push(extModule)
           onProgress(`  Extension loaded: ${url}`)
         } catch (err) {
           onProgress(`  Warning: Extension failed to load: ${ext} (${err.message})`)
@@ -537,6 +530,17 @@ export async function prerenderSite(siteDir, options = {}) {
       }
     }
 
+    // Initialize the Uniweb runtime using the shared SSR module
+    const uniweb = initPrerender(siteContent, foundation, loadedExtensions, { onProgress })
+
+    // Build-specific: pre-populate DataStore so EntityStore can resolve data during prerender.
+    // Use the framework's default cache key so runtime probes hit the same entries.
+    if (fetchedData.length > 0 && uniweb.activeWebsite?.dataStore) {
+      for (const entry of fetchedData) {
+        uniweb.activeWebsite.dataStore.set(deriveCacheKey(entry.config), { data: entry.data })
+      }
+    }
+
     // Pre-fetch icons for SSR embedding
     await prefetchIcons(siteContent, uniweb, onProgress)
 

package/src/runtime-schema.js

@@ -10,7 +10,18 @@
  * - defaults: param default values
  * - context: static capabilities for cross-block coordination
  * - initialState: initial values for mutable block state
- * - inheritData: boolean or array for cascaded data from page/site fetches
+ * - inheritData: internal flag for cascaded data delivery
+ *     true  → deliver all data available at ancestor levels (default)
+ *     false → deliver nothing (component opted out with `data: false`)
+ *
+ * Data delivery is default-on: a component without any `data:` field
+ * receives all data cascaded from its ancestor levels (block → page →
+ * parent page → site) via `content.data.{schema}`. A component that
+ * genuinely cannot tolerate ambient data declares `data: false`.
+ *
+ * `data: { entity: 'articles' }` is a **declaration**, not a gate. It
+ * tells the editor and prepare-props what shape the component expects,
+ * but does not restrict delivery.
  *
  * Full metadata (titles, descriptions, hints, etc.) stays in schema.json
  * for the visual editor.
@@ -202,39 +213,64 @@ export function extractRuntimeSchema(fullMeta) {
   }
 
   // Data binding (CMS entities)
-  // Supports both old format (data: 'person:6') and new consolidated format
-  // (data: { entity: 'person:6', schemas: {...}, inherit: [...] })
-  if (fullMeta.data) {
-    if (typeof fullMeta.data === 'string') {
-      // Old format: data: 'person:6'
-      const parsed = parseDataString(fullMeta.data)
+  //
+  // Supported forms:
+  //   data: false                            → explicit opt-out
+  //   data: { entity: 'person:6' }           → declaration + shape hints
+  //   data: { schemas: {...} }               → validation / default shapes
+  //   data: 'person:6'                       → legacy string form (declaration only)
+  //
+  // Deprecated forms (accepted with dev-mode warning, removed in next release):
+  //   data: { inherit: true | false | [...] }  — component-side gating is gone;
+  //                                              delivery is default-on
+  //   data: { detail, limit }                   — moved to block-level fetch
+  if (fullMeta.data === false) {
+    // Explicit opt-out — deliver nothing to this component.
+    runtime.inheritData = false
+  } else if (typeof fullMeta.data === 'string') {
+    // Legacy string form: data: 'person:6'
+    const parsed = parseDataString(fullMeta.data)
+    if (parsed) {
+      runtime.data = parsed
+    }
+  } else if (fullMeta.data && typeof fullMeta.data === 'object') {
+    if (fullMeta.data.entity) {
+      const parsed = parseDataString(fullMeta.data.entity)
       if (parsed) {
         runtime.data = parsed
       }
-    } else if (typeof fullMeta.data === 'object') {
-      // New format: data: { entity, schemas, inherit }
-      if (fullMeta.data.entity) {
-        const parsed = parseDataString(fullMeta.data.entity)
-        if (parsed) {
-          runtime.data = parsed
-        }
-      }
-      if (fullMeta.data.schemas) {
-        const schemas = extractSchemas(fullMeta.data.schemas)
-        if (schemas) {
-          runtime.schemas = schemas
-        }
+    }
+    if (fullMeta.data.schemas) {
+      const schemas = extractSchemas(fullMeta.data.schemas)
+      if (schemas) {
+        runtime.schemas = schemas
       }
-      if (fullMeta.data.inherit !== undefined) {
-        runtime.inheritData = fullMeta.data.inherit
+    }
+    // Deprecated: data.inherit is a no-op under default-on delivery. The
+    // only behavior we still honor is `inherit: false` → treat as opt-out,
+    // so existing foundations that wrote "don't deliver" still don't.
+    // Array and `true` forms are ignored — delivery happens regardless.
+    if (fullMeta.data.inherit === false) {
+      if (typeof process !== 'undefined' && process.env?.NODE_ENV !== 'production') {
+        console.warn(
+          '[uniweb] `data: { inherit: false }` is deprecated; use `data: false` instead.'
+        )
       }
-      // detail: false → opt out of single-item resolution on dynamic pages,
-      // returning the collection instead (minus the active item)
-      if (fullMeta.data.detail !== undefined) {
-        runtime.inheritDetail = fullMeta.data.detail
+      runtime.inheritData = false
+    } else if (fullMeta.data.inherit !== undefined) {
+      if (typeof process !== 'undefined' && process.env?.NODE_ENV !== 'production') {
+        console.warn(
+          '[uniweb] `data: { inherit: ... }` is deprecated; delivery is default-on. Remove the `inherit` field.'
+        )
       }
-      if (fullMeta.data.limit !== undefined) {
-        runtime.inheritLimit = fullMeta.data.limit
+    }
+    // Deprecated: detail/limit on the component side. Block-level
+    // `fetch: { inherit: true, detail, limit }` is where these belong now.
+    if (fullMeta.data.detail !== undefined || fullMeta.data.limit !== undefined) {
+      if (typeof process !== 'undefined' && process.env?.NODE_ENV !== 'production') {
+        console.warn(
+          '[uniweb] `data: { detail, limit }` on the component side is deprecated; set these on a block-level `fetch: { inherit: true, ... }` instead.'
+        )
       }
     }
   }
@@ -267,18 +303,17 @@ export function extractRuntimeSchema(fullMeta) {
     }
   }
 
-  // Data inheritance - component receives cascaded data from page/site level fetches
-  // Can be: true (inherit all), false (inherit none), or ['schema1', 'schema2'] (selective)
-  // Top-level inheritData supported for backwards compat (lower priority than data.inherit)
-  if (fullMeta.inheritData !== undefined && runtime.inheritData === undefined) {
-    runtime.inheritData = fullMeta.inheritData
+  // Top-level inheritData (legacy, pre-`data.*` format) — honored only as opt-out.
+  // Truthy values and arrays are ignored; delivery is default-on.
+  if (fullMeta.inheritData === false && runtime.inheritData === undefined) {
+    runtime.inheritData = false
   }
 
-  // Auto-derive inheritData from entity type when no explicit inherit is set.
-  // data: { entity: 'articles' } implies inheritData: ['articles']
-  if (runtime.data && runtime.inheritData === undefined) {
-    runtime.inheritData = [runtime.data.type]
-  }
+  // Data delivery is default-on. `runtime.inheritData` stays undefined unless
+  // the component explicitly opts out (runtime.inheritData === false), in
+  // which case EntityStore delivers nothing. The declaration `data.entity`
+  // no longer implies a gate — it's a hint consumed by prepare-props and
+  // the editor.
 
   return Object.keys(runtime).length > 0 ? runtime : null
 }

package/src/site/collection-processor.js

@@ -79,7 +79,8 @@ function parseCollectionConfig(name, config) {
       sort: null,
       filter: null,
       limit: 0,
-      excerpt: { maxLength: 160 }
+      excerpt: { maxLength: 160 },
+      deferred: null,
     }
   }
 
@@ -93,7 +94,24 @@ function parseCollectionConfig(name, config) {
     excerpt: {
       maxLength: config.excerpt?.maxLength || 160,
       field: config.excerpt?.field || null
-    }
+    },
+    // `deferred:` lists fields that are heavy (article body, full nested
+    // arrays). Those fields are stripped from the cascade payload that
+    // ships with `data: <name>` declarations, and per-record full files
+    // are emitted at public/data/<name>/<slug>.json. Components that
+    // need the full record fetch the per-record file on demand, either
+    // automatically on dynamic-route pages (entity-store routes the
+    // singular detail there) or via the kit's useEntityDetail hook.
+    deferred: Array.isArray(config.deferred) ? config.deferred.slice() : null,
+    // `queryable:` declares the queryable surface — which fields a
+    // foundation can offer for filtering UI, with their type and
+    // type-specific metadata (enum options, range bounds). Foundations
+    // read this metadata via the kit's useCollectionQueryable hook to
+    // render filter controls and compose where-objects from user
+    // interactions. The framework doesn't validate the shape here —
+    // foundations get whatever the author wrote; documentation defines
+    // the conventional types (enum/boolean/range/text).
+    queryable: (config.queryable && typeof config.queryable === 'object') ? config.queryable : null,
   }
 }
 
@@ -578,7 +596,7 @@ export async function processCollections(siteDir, collectionsConfig, collections
  * })
  * // Creates public/data/articles.json
  */
-export async function writeCollectionFiles(siteDir, collections) {
+export async function writeCollectionFiles(siteDir, collections, collectionsConfig = null) {
   if (!collections || Object.keys(collections).length === 0) {
     return
   }
@@ -587,9 +605,44 @@ export async function writeCollectionFiles(siteDir, collections) {
   await mkdir(dataDir, { recursive: true })
 
   for (const [name, items] of Object.entries(collections)) {
-    const filepath = join(dataDir, `${name}.json`)
-    await writeFile(filepath, JSON.stringify(items, null, 2))
-    console.log(`[collection-processor] Generated ${filepath} (${items.length} items)`)
+    const rawConfig = collectionsConfig?.[name]
+    const parsed = rawConfig ? parseCollectionConfig(name, rawConfig) : null
+    const deferred = parsed?.deferred
+
+    if (deferred && deferred.length > 0) {
+      // `deferred:` is set — emit two payloads:
+      //   1. The cascade JSON at /data/<name>.json with deferred fields stripped.
+      //      This is what `data: <name>` declarations deliver everywhere.
+      //   2. Per-record full files at /data/<name>/<slug>.json with every field.
+      //      Dynamic-route singular fetches and useEntityDetail hooks read these.
+      const recordsDir = join(dataDir, name)
+      await mkdir(recordsDir, { recursive: true })
+
+      let perRecordCount = 0
+      for (const item of items) {
+        if (!item || typeof item !== 'object' || !item.slug) continue
+        const recordPath = join(recordsDir, `${item.slug}.json`)
+        await writeFile(recordPath, JSON.stringify(item, null, 2))
+        perRecordCount++
+      }
+
+      const stripped = items.map((item) => {
+        if (!item || typeof item !== 'object') return item
+        const out = { ...item }
+        for (const field of deferred) delete out[field]
+        return out
+      })
+      const cascadePath = join(dataDir, `${name}.json`)
+      await writeFile(cascadePath, JSON.stringify(stripped, null, 2))
+      console.log(
+        `[collection-processor] Generated ${cascadePath} (${items.length} items, ` +
+        `deferred: [${deferred.join(', ')}]) + ${perRecordCount} per-record files`
+      )
+    } else {
+      const filepath = join(dataDir, `${name}.json`)
+      await writeFile(filepath, JSON.stringify(items, null, 2))
+      console.log(`[collection-processor] Generated ${filepath} (${items.length} items)`)
+    }
   }
 }
 

package/src/site/data-fetcher.js

@@ -20,6 +20,7 @@ import { readFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import { existsSync } from 'node:fs'
 import yaml from 'js-yaml'
+import { matchWhere } from '@uniweb/core'
 
 /**
  * Infer schema name from path or URL
@@ -157,19 +158,52 @@ export function applySort(items, sortExpr) {
 }
 
 /**
- * Apply post-processing to fetched data (filter, sort, limit)
+ * Apply a where-object predicate to an array of items.
+ *
+ * The where-object is the new query language (see @uniweb/core's
+ * matchWhere and the architecture doc at
+ * kb/framework/architecture/data-fetching.md). Structured JSON
+ * predicate; the runtime evaluator walks the object against each
+ * record. Same shape ships to backends that declare `supports: [where]`.
+ *
+ * @param {Array} items - Items to filter
+ * @param {object} where - Where-object predicate
+ * @returns {Array} Filtered items in source order
+ */
+export function applyWhere(items, where) {
+  if (!where || !Array.isArray(items)) return items
+  return matchWhere(where, items)
+}
+
+/**
+ * Apply post-processing to fetched data (where, filter, sort, limit)
+ *
+ * Order of operations:
+ *   1. where (where-object predicate, new) — narrows the record set
+ *   2. filter (legacy DSL string) — narrows further if both are set; deprecated
+ *   3. sort
+ *   4. limit
+ *
+ * `where:` and `filter:` may both appear during the deprecation window
+ * but in practice authors should pick one. Using `filter:` emits a dev
+ * warning at parse time (see parseFetchConfig).
  *
  * @param {any} data - Fetched data
- * @param {object} config - Fetch config with optional filter, sort, limit
+ * @param {object} config - Fetch config with optional where, filter, sort, limit
  * @returns {any} Processed data
  */
 export function applyPostProcessing(data, config) {
   if (!data || !Array.isArray(data)) return data
-  if (!config.filter && !config.sort && !config.limit) return data
+  if (!config.where && !config.filter && !config.sort && !config.limit) return data
 
   let result = data
 
-  // Apply filter first
+  // Apply where-object predicate first (new path)
+  if (config.where) {
+    result = applyWhere(result, config.where)
+  }
+
+  // Apply legacy filter expression (deprecated)
   if (config.filter) {
     result = applyFilter(result, config.filter)
   }
@@ -225,20 +259,37 @@ export function parseFetchConfig(fetch) {
   // Full config object
   if (typeof fetch !== 'object') return null
 
-  // Inherit-merge config: { inherit: true, detail: false, limit: 3 }
-  // No URL — merges with the parent fetch config at runtime; only carries override props.
-  if (fetch.inherit === true) {
+  // Refine config: { refine: true, detail: false, limit: 3 }
+  // No URL — merges with the parent fetch config at runtime; only carries
+  // override props. The legacy spelling `inherit: true` is accepted for one
+  // release with a warning, then removed.
+  //
+  // Note on build-vs-runtime scope: this parser passes `sort` and `filter`
+  // through on refine configs, but the runtime EntityStore only applies
+  // `detail`, `limit`, and `order` overrides. `sort` / `filter` on a refine
+  // block are currently accepted by the parser but not honored at runtime.
+  // Preserved as-is in this rename commit; revisit separately if needed.
+  if (fetch.refine === true || fetch.inherit === true) {
+    if (fetch.inherit === true && fetch.refine !== true) {
+      console.warn(
+        "[uniweb] 'fetch: { inherit: true }' is deprecated; rename to 'fetch: { refine: true }'. " +
+        'Accepted for one release; will be removed in the next minor.'
+      )
+    }
+    if (fetch.filter !== undefined) warnFilterDeprecated()
     return {
-      inherit: true,
+      refine: true,
       ...(fetch.detail !== undefined ? { detail: fetch.detail } : {}),
       ...(fetch.limit !== undefined ? { limit: fetch.limit } : {}),
       ...(fetch.sort !== undefined ? { sort: fetch.sort } : {}),
+      ...(fetch.where !== undefined ? { where: fetch.where } : {}),
       ...(fetch.filter !== undefined ? { filter: fetch.filter } : {}),
     }
   }
 
   // Collection reference: { collection: 'articles', limit: 3 }
   if (fetch.collection) {
+    if (fetch.filter !== undefined) warnFilterDeprecated()
     return {
       path: `/data/${fetch.collection}.json`,
       url: undefined,
@@ -246,9 +297,11 @@ export function parseFetchConfig(fetch) {
       prerender: fetch.prerender ?? true,
       merge: fetch.merge ?? false,
       transform: fetch.transform,
-      // Post-processing options
+      // Query operators
+      where: fetch.where,
       limit: fetch.limit,
       sort: fetch.sort,
+      // Legacy post-processing (deprecated, see warning above)
       filter: fetch.filter,
     }
   }
@@ -261,15 +314,19 @@ export function parseFetchConfig(fetch) {
     merge = false,
     transform,
     detail,
-    // Post-processing options (also supported for path/url fetches)
+    // Query operators
+    where,
     limit,
     sort,
+    // Legacy post-processing (deprecated)
     filter,
   } = fetch
 
   // Must have either path or url
   if (!path && !url) return null
 
+  if (filter !== undefined) warnFilterDeprecated()
+
   return {
     path,
     url,
@@ -278,13 +335,27 @@ export function parseFetchConfig(fetch) {
     merge,
     transform,
     detail,
-    // Post-processing options
+    // Query operators
+    where,
     limit,
     sort,
+    // Legacy post-processing (deprecated)
     filter,
   }
 }
 
+let filterDeprecationWarned = false
+function warnFilterDeprecated() {
+  if (filterDeprecationWarned) return
+  filterDeprecationWarned = true
+  console.warn(
+    "[uniweb] 'fetch: { filter: ... }' (DSL string) is deprecated; use 'where: { ... }' " +
+    'with a where-object. Example: where: { tags: \"featured\" } instead of ' +
+    "filter: 'tags contains featured'. " +
+    'Accepted for one release; will be removed in the next minor.'
+  )
+}
+
 /**
  * Execute a fetch operation
  *

package/src/site/plugin.js

@@ -556,7 +556,7 @@ export function siteContentPlugin(options = {}) {
           if (collectionsConfig) {
             console.log('[site-content] Processing content collections...')
             const collections = await processCollections(resolvedSitePath, collectionsConfig, resolvedCollectionsBase, basePath)
-            await writeCollectionFiles(resolvedSitePath, collections)
+            await writeCollectionFiles(resolvedSitePath, collections, collectionsConfig)
           }
         } catch (err) {
           console.warn('[site-content] Early collection processing failed:', err.message)
@@ -593,7 +593,7 @@ export function siteContentPlugin(options = {}) {
         if (isProduction && siteContent.config?.collections) {
           console.log('[site-content] Processing content collections...')
           const collections = await processCollections(resolvedSitePath, siteContent.config.collections, resolvedCollectionsBase, basePath)
-          await writeCollectionFiles(resolvedSitePath, collections)
+          await writeCollectionFiles(resolvedSitePath, collections, siteContent.config.collections)
         }
 
         // Execute data fetches in dev mode
@@ -656,7 +656,7 @@ export function siteContentPlugin(options = {}) {
               const collections = collectionsConfig || siteContent?.config?.collections
               if (collections) {
                 const processed = await processCollections(resolvedSitePath, collections, resolvedCollectionsBase, basePath)
-                await writeCollectionFiles(resolvedSitePath, processed)
+                await writeCollectionFiles(resolvedSitePath, processed, collections)
               }
               // Send full reload to client
               server.ws.send({ type: 'full-reload' })