@uniweb/core 0.3.10 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/core",
-  "version": "0.3.10",
+  "version": "0.4.0",
   "description": "Core classes for the Uniweb platform - Uniweb, Website, Page, Block",
   "type": "module",
   "exports": {
@@ -30,7 +30,7 @@
     "jest": "^29.7.0"
   },
   "dependencies": {
-    "@uniweb/semantic-parser": "1.0.17"
+    "@uniweb/semantic-parser": "1.1.0"
   },
   "scripts": {
     "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js"

package/src/block.js

@@ -43,10 +43,27 @@ export default class Block {
     // Block configuration
     const blockConfig = blockData.params || blockData.config || {}
     this.preset = blockData.preset
-    this.themeName = blockConfig.theme || 'light'
+
+    // Normalize theme: supports string ("light") or object ({ mode, ...tokenOverrides })
+    const rawTheme = blockConfig.theme
+    if (rawTheme && typeof rawTheme === 'object') {
+      const { mode, ...overrides } = rawTheme
+      this.themeName = mode || 'light'
+      this.contextOverrides = Object.keys(overrides).length > 0 ? overrides : null
+    } else {
+      this.themeName = rawTheme || 'light'
+      this.contextOverrides = null
+    }
+
     this.standardOptions = blockConfig.standardOptions || {}
     this.properties = blockConfig.properties || blockConfig
 
+    // Normalize params.theme to string so components always see "light"/"dark"/"medium",
+    // not the raw object. Done after properties assignment to avoid mutating source data.
+    if (this.properties.theme && typeof this.properties.theme === 'object') {
+      this.properties = { ...this.properties, theme: this.themeName }
+    }
+
     // Extract background from params into standardOptions
     // Content authors set background in section frontmatter; the runtime
     // reads it from standardOptions to render the Background component.
@@ -67,9 +84,9 @@ export default class Block {
     // Supports local files (path) or remote URLs (url)
     this.fetch = blockData.fetch || null
 
-    // Cascaded data from page/site level fetches
-    // Populated during render for components with inheritData
-    this.cascadedData = blockData.cascadedData || {}
+    // Data loading state — set by BlockRenderer when a runtime fetch is in progress
+    // Components check this to show loading UI (spinners, skeletons)
+    this.dataLoading = false
 
     // Dynamic route context (params from URL matching)
     // Set when accessing a dynamic page like /blog/:slug -> /blog/my-post
@@ -89,7 +106,7 @@ export default class Block {
    * Supports multiple content formats:
    * 1. Pre-parsed groups structure (from editor)
    * 2. ProseMirror document (from markdown collection)
-   * 3. Simple key-value content (PoC style)
+   * 3. Plain object (passed through directly)
    *
    * Uses @uniweb/semantic-parser for rich content extraction including:
    * - Pretitle detection (H3 before H1)
@@ -108,20 +125,18 @@ export default class Block {
       return this.extractFromProseMirror(content)
     }
 
-    // Simple key-value content (PoC style) - pass through directly
-    // This allows components to receive content like { title, subtitle, items }
+    // Plain object content — pass through directly.
+    // guaranteeContentStructure() in prepare-props will fill in missing fields.
     if (content && typeof content === 'object' && !Array.isArray(content)) {
-      // Mark as PoC format so runtime can detect and pass through
-      return {
-        _isPoc: true,
-        _pocContent: content
-      }
+      return content
     }
 
-    // Fallback
+    // Fallback — empty flat structure
     return {
-      main: { header: {}, body: {} },
-      items: []
+      title: '',
+      paragraphs: [],
+      items: [],
+      sequence: []
     }
   }
 
@@ -315,6 +330,7 @@ export default class Block {
     return {
       type: this.type,
       theme: this.themeName,
+      contextOverrides: this.contextOverrides,
       state: this.state,
       context: this.context
     }
@@ -381,63 +397,6 @@ export default class Block {
     return this.dynamicContext
   }
 
-  /**
-   * Get the current item from cascaded data using dynamic route params
-   * Looks up the item in cascadedData that matches the URL param value
-   *
-   * @param {string} [schema] - Schema name to look up (e.g., 'articles'). If omitted, uses parentSchema from dynamicContext.
-   * @returns {Object|null} The matched item, or null if not found
-   *
-   * @example
-   * // URL: /blog/my-post, cascadedData: { articles: [{slug: 'my-post', title: 'My Post'}, ...] }
-   * block.getCurrentItem('articles')
-   * // { slug: 'my-post', title: 'My Post', ... }
-   */
-  getCurrentItem(schema) {
-    const ctx = this.dynamicContext
-    if (!ctx) return null
-
-    const { paramName, paramValue } = ctx
-
-    // If schema not provided, try to infer from cascadedData keys
-    const lookupSchema = schema || this._inferSchema()
-    if (!lookupSchema) return null
-
-    const items = this.cascadedData[lookupSchema]
-    if (!Array.isArray(items)) return null
-
-    // Find item where the param field matches the URL value
-    return items.find(item => String(item[paramName]) === String(paramValue)) || null
-  }
-
-  /**
-   * Get all items from cascaded data for the dynamic route's schema
-   *
-   * @param {string} [schema] - Schema name to look up. If omitted, uses parentSchema from dynamicContext.
-   * @returns {Array} Array of items, or empty array if not found
-   */
-  getAllItems(schema) {
-    const lookupSchema = schema || this._inferSchema()
-    if (!lookupSchema) return []
-
-    const items = this.cascadedData[lookupSchema]
-    return Array.isArray(items) ? items : []
-  }
-
-  /**
-   * Infer the schema name from cascaded data keys
-   * Looks for the first array in cascadedData
-   * @private
-   */
-  _inferSchema() {
-    for (const key of Object.keys(this.cascadedData)) {
-      if (Array.isArray(this.cascadedData[key])) {
-        return key
-      }
-    }
-    return null
-  }
-
   /**
    * Normalize a background value from section frontmatter
    *
@@ -451,15 +410,23 @@ export default class Block {
    * @returns {Object} Normalized background config with mode
    */
   static normalizeBackground(raw) {
-    // String URL shorthand
+    // String shorthand — classify by content
     if (typeof raw === 'string') {
-      const ext = raw.split('.').pop()?.toLowerCase()
-      const isVideo = ['mp4', 'webm', 'ogv', 'ogg'].includes(ext)
+      // URL or path → image/video
+      if (/^(\/|\.\/|\.\.\/|https?:\/\/)/.test(raw) || /\.(jpe?g|png|webp|gif|svg|avif|mp4|webm|ogv|ogg)$/i.test(raw)) {
+        const ext = raw.split('.').pop()?.toLowerCase()
+        const isVideo = ['mp4', 'webm', 'ogv', 'ogg'].includes(ext)
+        if (isVideo) return { mode: 'video', video: { src: raw } }
+        return { mode: 'image', image: { src: raw } }
+      }
 
-      if (isVideo) {
-        return { mode: 'video', video: { src: raw } }
+      // CSS gradient function
+      if (/^(linear|radial|conic)-gradient\(/.test(raw)) {
+        return { mode: 'gradient', gradient: raw }
       }
-      return { mode: 'image', image: { src: raw } }
+
+      // Anything else → CSS color (hex, rgb, hsl, oklch, named color, var())
+      return { mode: 'color', color: raw }
     }
 
     // Object with explicit mode — pass through

package/src/datastore.js

@@ -0,0 +1,113 @@
+/**
+ * DataStore
+ *
+ * Runtime data cache that persists across SPA navigation.
+ * Deduplicates in-flight fetches so concurrent callers share a single request.
+ *
+ * Core can't import runtime, so the fetcher function is registered at startup
+ * via registerFetcher().
+ */
+
+/**
+ * Build a stable cache key from a fetch config.
+ * Only includes fields that affect the response.
+ *
+ * @param {Object} config
+ * @returns {string}
+ */
+function cacheKey(config) {
+  const { path, url, schema, transform } = config
+  return JSON.stringify({ path, url, schema, transform })
+}
+
+export default class DataStore {
+  constructor() {
+    this._cache = new Map()
+    this._inflight = new Map()
+    this._fetcher = null
+  }
+
+  /**
+   * Register the fetcher function (called by runtime at startup).
+   * @param {Function} fn - (config) => Promise<{ data, error? }>
+   */
+  registerFetcher(fn) {
+    this._fetcher = fn
+  }
+
+  /**
+   * Check whether data for this config is cached.
+   * @param {Object} config - Fetch config
+   * @returns {boolean}
+   */
+  has(config) {
+    return this._cache.has(cacheKey(config))
+  }
+
+  /**
+   * Return cached data, or null on miss.
+   * @param {Object} config - Fetch config
+   * @returns {any|null}
+   */
+  get(config) {
+    const key = cacheKey(config)
+    return this._cache.has(key) ? this._cache.get(key) : null
+  }
+
+  /**
+   * Store data in the cache.
+   * @param {Object} config - Fetch config
+   * @param {any} data
+   */
+  set(config, data) {
+    this._cache.set(cacheKey(config), data)
+  }
+
+  /**
+   * Fetch data with caching and in-flight deduplication.
+   *
+   * - Cache hit: returns immediately.
+   * - In-flight: returns existing promise (no duplicate request).
+   * - Miss: calls the registered fetcher, caches the result.
+   *
+   * @param {Object} config - Fetch config
+   * @returns {Promise<{ data: any, error?: string }>}
+   */
+  async fetch(config) {
+    if (!this._fetcher) {
+      throw new Error('DataStore: no fetcher registered. Call registerFetcher() first.')
+    }
+
+    const key = cacheKey(config)
+
+    // Cache hit
+    if (this._cache.has(key)) {
+      return { data: this._cache.get(key) }
+    }
+
+    // In-flight dedup
+    if (this._inflight.has(key)) {
+      return this._inflight.get(key)
+    }
+
+    // Miss — execute fetch
+    const promise = this._fetcher(config).then((result) => {
+      this._inflight.delete(key)
+      if (result.data !== undefined && result.data !== null) {
+        this._cache.set(key, result.data)
+      }
+      return result
+    })
+
+    this._inflight.set(key, promise)
+    return promise
+  }
+
+  /**
+   * Flush cache and in-flight map.
+   */
+  clear() {
+    this._cache.clear()
+    this._inflight.clear()
+  }
+}

package/src/entity-store.js

@@ -0,0 +1,276 @@
+/**
+ * EntityStore
+ *
+ * Resolves entity data for components by walking the page hierarchy.
+ * Leverages DataStore for caching and deduplication.
+ *
+ * Two-method API:
+ * - resolve(block, meta) — sync, reads cache only
+ * - fetch(block, meta)   — async, fetches missing data via DataStore
+ */
+
+import singularize from './singularize.js'
+
+export default class EntityStore {
+  /**
+   * @param {Object} options
+   * @param {import('./datastore.js').default} options.dataStore
+   */
+  constructor({ dataStore }) {
+    this.dataStore = dataStore
+  }
+
+  /**
+   * Determine which schemas a component requests.
+   *
+   * @param {Object} meta - Component runtime metadata
+   * @returns {string[]|null} Array of schema names, or null if none requested
+   */
+  _getRequestedSchemas(meta) {
+    if (!meta) return null
+
+    const inheritData = meta.inheritData
+    if (!inheritData) return null
+
+    // inheritData: true → inherit all (resolved from fetch configs)
+    // inheritData: ['articles'] → specific schemas
+    if (Array.isArray(inheritData)) return inheritData.length > 0 ? inheritData : null
+    if (inheritData === true) return [] // empty = "all available"
+
+    return null
+  }
+
+  /**
+   * Walk the hierarchy to find fetch configs for requested schemas.
+   * Order: block.fetch → page.fetch → parent.fetch → site config.fetch
+   * First match per schema wins. Only walks one parent level (auto-wiring).
+   *
+   * @param {import('./block.js').default} block
+   * @param {string[]} requested - Schema names (empty = collect all)
+   * @returns {Map<string, Object>} schema → fetch config
+   */
+  _findFetchConfigs(block, requested) {
+    const configs = new Map()
+    const collectAll = requested.length === 0
+
+    const sources = []
+
+    // 1. Block-level fetch
+    if (block.fetch) {
+      sources.push(block.fetch)
+    }
+
+    // 2. Page-level fetch
+    const page = block.page
+    if (page?.fetch) {
+      sources.push(page.fetch)
+    }
+
+    // 3. Parent page fetch (one level — auto-wiring for dynamic routes)
+    if (page?.parent?.fetch) {
+      sources.push(page.parent.fetch)
+    }
+
+    // 4. Site-level fetch
+    const siteFetch = block.website?.config?.fetch
+    if (siteFetch) {
+      sources.push(siteFetch)
+    }
+
+    for (const source of sources) {
+      // Normalize: single config or array of configs
+      const configList = Array.isArray(source) ? source : [source]
+
+      for (const cfg of configList) {
+        if (!cfg.schema) continue
+        if (configs.has(cfg.schema)) continue // first match wins
+
+        if (collectAll || requested.includes(cfg.schema)) {
+          configs.set(cfg.schema, cfg)
+        }
+      }
+    }
+
+    return configs
+  }
+
+  /**
+   * Build a fetch config for a single entity using the detail convention.
+   *
+   * @param {Object} collectionConfig - The collection's fetch config (must have `detail`)
+   * @param {Object} dynamicContext - { paramName, paramValue, schema }
+   * @returns {Object|null} A fetch config for the single entity, or null
+   */
+  _buildDetailConfig(collectionConfig, dynamicContext) {
+    const { detail } = collectionConfig
+    if (!detail) return null
+
+    const { paramName, paramValue } = dynamicContext
+    if (!paramName || paramValue === undefined) return null
+
+    const baseUrl = collectionConfig.url || collectionConfig.path
+    if (!baseUrl) return null
+
+    let detailUrl
+
+    if (detail === 'rest') {
+      // REST convention: {baseUrl}/{paramValue}
+      detailUrl = `${baseUrl.replace(/\/$/, '')}/${encodeURIComponent(paramValue)}`
+    } else if (detail === 'query') {
+      // Query param convention: {baseUrl}?{paramName}={paramValue}
+      const sep = baseUrl.includes('?') ? '&' : '?'
+      detailUrl = `${baseUrl}${sep}${paramName}=${encodeURIComponent(paramValue)}`
+    } else {
+      // Custom pattern: replace {paramName} placeholders
+      detailUrl = detail.replace(/\{(\w+)\}/g, (_, key) => {
+        if (key === paramName) return encodeURIComponent(paramValue)
+        return `{${key}}` // leave unknown placeholders
+      })
+    }
+
+    // Build a fetch config for the single item
+    const isLocalPath = !!collectionConfig.path && !collectionConfig.url
+    return {
+      ...(isLocalPath ? { path: detailUrl } : { url: detailUrl }),
+      schema: singularize(collectionConfig.schema) || collectionConfig.schema,
+      transform: collectionConfig.transform,
+    }
+  }
+
+  /**
+   * Resolve singular item for dynamic routes.
+   * If block/page has dynamicContext, find the matching item in the collection.
+   *
+   * @param {Object} data - Resolved entity data { schema: items[] }
+   * @param {Object|null} dynamicContext
+   * @returns {Object} data with singular key added if applicable
+   */
+  _resolveSingularItem(data, dynamicContext) {
+    if (!dynamicContext) return data
+
+    const { paramName, paramValue, schema: pluralSchema } = dynamicContext
+    if (!pluralSchema || !paramName || paramValue === undefined) return data
+
+    const items = data[pluralSchema]
+    if (!Array.isArray(items)) return data
+
+    const singularSchema = singularize(pluralSchema)
+    const currentItem = items.find(
+      (item) => String(item[paramName]) === String(paramValue)
+    )
+
+    if (currentItem && singularSchema) {
+      return { ...data, [singularSchema]: currentItem }
+    }
+
+    return data
+  }
+
+  /**
+   * Sync resolution. Checks DataStore cache for fetch configs found in hierarchy.
+   *
+   * @param {import('./block.js').default} block
+   * @param {Object} meta - Component runtime metadata
+   * @returns {{ status: 'ready'|'pending'|'none', data: Object|null }}
+   */
+  resolve(block, meta) {
+    const requested = this._getRequestedSchemas(meta)
+    if (requested === null) {
+      return { status: 'none', data: null }
+    }
+
+    // Walk hierarchy for fetch configs
+    const configs = this._findFetchConfigs(block, requested)
+    if (configs.size === 0) {
+      return { status: 'none', data: null }
+    }
+
+    // Check DataStore cache for each config
+    const dynamicContext = block.dynamicContext || block.page?.dynamicContext
+    const data = {}
+    let allCached = true
+
+    for (const [schema, cfg] of configs) {
+      if (this.dataStore.has(cfg)) {
+        data[schema] = this.dataStore.get(cfg)
+      } else if (dynamicContext && cfg.detail) {
+        // Detail query: check if the single-entity result is cached
+        const detailCfg = this._buildDetailConfig(cfg, dynamicContext)
+        if (detailCfg && this.dataStore.has(detailCfg)) {
+          const singularKey = singularize(schema) || schema
+          data[singularKey] = this.dataStore.get(detailCfg)
+        } else {
+          allCached = false
+        }
+      } else {
+        allCached = false
+      }
+    }
+
+    if (allCached) {
+      const resolved = this._resolveSingularItem(data, dynamicContext)
+      return { status: 'ready', data: resolved }
+    }
+
+    return { status: 'pending', data: null }
+  }
+
+  /**
+   * Async fetch. Walks hierarchy, fetches missing data via DataStore.
+   *
+   * @param {import('./block.js').default} block
+   * @param {Object} meta - Component runtime metadata
+   * @returns {Promise<{ data: Object|null }>}
+   */
+  async fetch(block, meta) {
+    const requested = this._getRequestedSchemas(meta)
+    if (requested === null) {
+      return { data: null }
+    }
+
+    const configs = this._findFetchConfigs(block, requested)
+    if (configs.size === 0) {
+      return { data: null }
+    }
+
+    // Fetch all missing configs in parallel
+    const dynamicContext = block.dynamicContext || block.page?.dynamicContext
+    const data = {}
+    const fetchPromises = []
+
+    for (const [schema, cfg] of configs) {
+      // Detail query optimization: on template pages, if the collection
+      // isn't cached and a detail convention is defined, fetch just the
+      // single entity instead of the full collection.
+      if (dynamicContext && cfg.detail && !this.dataStore.has(cfg)) {
+        const detailCfg = this._buildDetailConfig(cfg, dynamicContext)
+        if (detailCfg) {
+          fetchPromises.push(
+            this.dataStore.fetch(detailCfg).then((result) => {
+              if (result.data !== undefined && result.data !== null) {
+                const singularKey = singularize(schema) || schema
+                data[singularKey] = result.data
+              }
+            })
+          )
+          continue // skip collection fetch for this schema
+        }
+      }
+
+      // Default: fetch the full collection
+      fetchPromises.push(
+        this.dataStore.fetch(cfg).then((result) => {
+          if (result.data !== undefined && result.data !== null) {
+            data[schema] = result.data
+          }
+        })
+      )
+    }
+
+    if (fetchPromises.length > 0) {
+      await Promise.all(fetchPromises)
+    }
+    const resolved = this._resolveSingularItem(data, dynamicContext)
+    return { data: resolved }
+  }
+}

package/src/index.js

@@ -15,6 +15,8 @@ export { default as Block } from './block.js'
 export { default as Input } from './input.js'
 export { default as Analytics } from './analytics.js'
 export { default as Theme } from './theme.js'
+export { default as DataStore } from './datastore.js'
+export { default as EntityStore } from './entity-store.js'
 
 /**
  * The singleton Uniweb instance.

package/src/page.js

@@ -53,6 +53,9 @@ export default class Page {
       priority: pageData.seo?.priority || null,
     }
 
+    // Parent page (set by Website.buildPageHierarchy())
+    this.parent = null
+
     // Child pages (for nested hierarchy) - populated by Website
     this.children = []
 
@@ -62,6 +65,10 @@ export default class Page {
     // Scroll position memory (for navigation restoration)
     this.scrollY = 0
 
+    // Fetch configuration (from page.yml data: field)
+    // Preserved at runtime so EntityStore can walk the page hierarchy
+    this.fetch = pageData.fetch || null
+
     // Dynamic route context (for pages created from dynamic routes like /blog/:slug)
     this.dynamicContext = pageData.dynamicContext || null
 

package/src/singularize.js

@@ -0,0 +1,40 @@
+/**
+ * Singularize a plural schema name
+ *
+ * Converts common English plural forms to singular.
+ * Used by EntityStore to derive singular keys (e.g., 'articles' → 'article').
+ *
+ * @param {string} name - Plural name
+ * @returns {string} Singular form
+ */
+export default function singularize(name) {
+  if (!name) return name
+  // Common irregular plurals
+  const irregulars = {
+    people: 'person',
+    children: 'child',
+    men: 'men',
+    women: 'woman',
+    series: 'series',
+  }
+  if (irregulars[name]) return irregulars[name]
+  // -ies → -y (categories → category)
+  if (name.endsWith('ies')) return name.slice(0, -3) + 'y'
+  // -es endings that should only remove 's' (not 'es')
+  // e.g., articles → article, courses → course
+  if (name.endsWith('es')) {
+    // Check if the base word ends in a consonant that requires 'es' plural
+    // (boxes, dishes, classes, heroes) vs just 's' plural (articles, courses)
+    const base = name.slice(0, -2)
+    const lastChar = base.slice(-1)
+    // If base ends in s, x, z, ch, sh - these need 'es' for plural, so remove 'es'
+    if (['s', 'x', 'z'].includes(lastChar) || base.endsWith('ch') || base.endsWith('sh')) {
+      return base
+    }
+    // Otherwise just remove 's' (articles → article)
+    return name.slice(0, -1)
+  }
+  // Regular -s plurals
+  if (name.endsWith('s')) return name.slice(0, -1)
+  return name
+}

package/src/website.js

@@ -5,6 +5,9 @@
  */
 
 import Page from './page.js'
+import DataStore from './datastore.js'
+import EntityStore from './entity-store.js'
+import singularize from './singularize.js'
 
 export default class Website {
   constructor(websiteData) {
@@ -79,6 +82,12 @@ export default class Website {
     // Deployment base path (set by runtime via setBasePath())
     this.basePath = ''
 
+    // Runtime data cache (fetcher registered by runtime at startup)
+    this.dataStore = new DataStore()
+
+    // Entity-aware query resolution (uses DataStore for caching)
+    this.entityStore = new EntityStore({ dataStore: this.dataStore })
+
     // Versioned scopes: route → { versions, latestId }
     // Scopes are routes where versioning starts (e.g., '/docs')
     this.versionedScopes = versionedScopes
@@ -368,51 +377,44 @@ export default class Website {
       singularSchema,
     }
 
-    // Get the parent page's data to find the items array
-    // Parent route is the template route without the :param suffix
+    // Set dynamic context on sections so Block instances receive it
+    if (pageData.sections && Array.isArray(pageData.sections)) {
+      for (const section of pageData.sections) {
+        section.dynamicContext = pageData.dynamicContext
+      }
+    }
+
+    // Try to resolve page metadata from DataStore
+    // Look up the parent page's fetch config to find data in the store
     const parentRoute = templatePage.route.replace(/\/:[\w]+$/, '') || '/'
     const parentPage = this.pages.find(p => p.route === parentRoute || p.getNavRoute() === parentRoute)
 
-    // Get items from parent's cascaded data
-    let items = []
-    let currentItem = null
-
     if (parentPage && pluralSchema) {
-      // Get items from parent page's first section's cascadedData
-      // This is where the page-level fetch stores its data
-      const firstSection = parentPage.pageBlocks?.body?.[0]
-      if (firstSection) {
-        items = firstSection.cascadedData?.[pluralSchema] || []
-      }
-
-      // Find the current item using the param
-      if (items.length > 0) {
-        currentItem = items.find(item => String(item[paramName]) === String(paramValue))
+      // Find collection data from parent's fetch config via DataStore
+      const parentFetch = parentPage.fetch
+      let items = []
+
+      if (parentFetch) {
+        const fetchConfig = Array.isArray(parentFetch)
+          ? parentFetch.find(f => f.schema === pluralSchema)
+          : (parentFetch.schema === pluralSchema ? parentFetch : null)
+        if (fetchConfig) {
+          items = this.dataStore.get(fetchConfig) || []
+        }
       }
-    }
 
-    // Store items in dynamic context for Block.getCurrentItem() / getAllItems()
-    pageData.dynamicContext.currentItem = currentItem
-    pageData.dynamicContext.allItems = items
+      const currentItem = items.find(item => String(item[paramName]) === String(paramValue))
 
-    // Inject cascaded data into sections for components with inheritData
-    // This provides both singular (article) and plural (articles) data
-    const cascadedData = {}
-    if (currentItem && singularSchema) {
-      cascadedData[singularSchema] = currentItem
-    }
-    if (items.length > 0 && pluralSchema) {
-      cascadedData[pluralSchema] = items
-    }
-
-    this._injectDynamicData(pageData.sections, cascadedData, pageData.dynamicContext)
-
-    // Update page metadata from current item if available
-    if (currentItem) {
-      if (currentItem.title) pageData.title = currentItem.title
-      if (currentItem.description || currentItem.excerpt) {
-        pageData.description = currentItem.description || currentItem.excerpt
+      if (currentItem) {
+        if (currentItem.title) pageData.title = currentItem.title
+        if (currentItem.description || currentItem.excerpt) {
+          pageData.description = currentItem.description || currentItem.excerpt
+        }
       }
+
+      // Store in dynamic context for entity resolution
+      pageData.dynamicContext.currentItem = currentItem || null
+      pageData.dynamicContext.allItems = items
     }
 
     // Create the page instance
@@ -437,64 +439,7 @@ export default class Website {
    * @private
    */
   _singularize(name) {
-    if (!name) return name
-    // Common irregular plurals
-    const irregulars = {
-      people: 'person',
-      children: 'child',
-      men: 'men',
-      women: 'woman',
-      series: 'series',
-    }
-    if (irregulars[name]) return irregulars[name]
-    // -ies → -y (categories → category)
-    if (name.endsWith('ies')) return name.slice(0, -3) + 'y'
-    // -es endings that should only remove 's' (not 'es')
-    // e.g., articles → article, courses → course
-    if (name.endsWith('es')) {
-      // Check if the base word ends in a consonant that requires 'es' plural
-      // (boxes, dishes, classes, heroes) vs just 's' plural (articles, courses)
-      const base = name.slice(0, -2)
-      const lastChar = base.slice(-1)
-      // If base ends in s, x, z, ch, sh - these need 'es' for plural, so remove 'es'
-      if (['s', 'x', 'z'].includes(lastChar) || base.endsWith('ch') || base.endsWith('sh')) {
-        return base
-      }
-      // Otherwise just remove 's' (articles → article)
-      return name.slice(0, -1)
-    }
-    // Regular -s plurals
-    if (name.endsWith('s')) return name.slice(0, -1)
-    return name
-  }
-
-  /**
-   * Inject dynamic route data into sections for components with inheritData
-   * This provides both the current item (singular) and all items (plural)
-   *
-   * @private
-   * @param {Array} sections - Sections to update
-   * @param {Object} cascadedData - Data to inject { article: {...}, articles: [...] }
-   * @param {Object} dynamicContext - Dynamic route context
-   */
-  _injectDynamicData(sections, cascadedData, dynamicContext) {
-    if (!sections || !Array.isArray(sections)) return
-
-    for (const section of sections) {
-      // Merge cascaded data into section's existing cascadedData
-      section.cascadedData = {
-        ...(section.cascadedData || {}),
-        ...cascadedData,
-      }
-
-      // Also set dynamic context for Block.getDynamicContext()
-      section.dynamicContext = dynamicContext
-
-      // Recurse into subsections
-      if (section.subsections && section.subsections.length > 0) {
-        this._injectDynamicData(section.subsections, cascadedData, dynamicContext)
-      }
-    }
+    return singularize(name)
   }
 
   /**
@@ -659,7 +604,7 @@ export default class Website {
    * @returns {string}
    */
   getLocaleUrl(localeCode, route = null) {
-    let targetRoute = route || this.activePage?.route || '/'
+    let targetRoute = route || this.activePage.route
 
     // Strip current locale prefix if present in route
     if (this.activeLocale && this.activeLocale !== this.defaultLocale) {
@@ -952,7 +897,7 @@ export default class Website {
    * website.getActiveRoute() // 'docs/getting-started'
    */
   getActiveRoute() {
-    return this.activePage?.getNormalizedRoute() || ''
+    return this.activePage.getNormalizedRoute()
   }
 
   /**