@symbo.ls/brender 3.14.7 → 3.14.8

package/load.js

@@ -0,0 +1,141 @@
+import { resolve, join } from 'path'
+import { existsSync, mkdirSync, writeFileSync, unlinkSync } from 'fs'
+import { tmpdir } from 'os'
+import { randomBytes } from 'crypto'
+
+/**
+ * Bundles a module entry point with esbuild so that extensionless imports,
+ * bare specifiers, and other bundler conventions resolve correctly.
+ * Returns the default + named exports of the bundled module, or null on failure.
+ */
+const bundleAndImport = async (entryPath) => {
+  if (!existsSync(entryPath)) return null
+
+  let esbuild
+  try {
+    esbuild = await import('esbuild')
+  } catch {
+    // Fallback: try raw import if esbuild is not available
+    try { return await import(entryPath) } catch { return null }
+  }
+
+  const outFile = join(tmpdir(), `brender_${randomBytes(8).toString('hex')}.mjs`)
+
+  try {
+    await esbuild.build({
+      entryPoints: [entryPath],
+      bundle: true,
+      format: 'esm',
+      platform: 'node',
+      outfile: outFile,
+      write: true,
+      logLevel: 'silent',
+      // Mark node builtins as external
+      external: ['fs', 'path', 'os', 'crypto', 'url', 'http', 'https', 'stream', 'util', 'events', 'buffer', 'child_process', 'worker_threads', 'net', 'tls', 'dns', 'dgram', 'zlib', 'assert', 'querystring', 'string_decoder', 'readline', 'perf_hooks', 'async_hooks', 'v8', 'vm', 'cluster', 'inspector', 'module', 'process', 'tty'],
+    })
+
+    const mod = await import(`file://${outFile}`)
+    return mod
+  } catch {
+    // Fallback: try raw import
+    try { return await import(entryPath) } catch { return null } // fallback: module not found via this resolver, trying next
+  } finally {
+    try { unlinkSync(outFile) } catch {} // cleanup: ignore if temp file already removed
+  }
+}
+
+/**
+ * Loads a Symbols project from a filesystem path.
+ * Expects the standard symbols/ directory structure.
+ *
+ * Uses esbuild to bundle each module so that extensionless imports
+ * and other bundler conventions work in Node.js.
+ *
+ * Used for prebuild scenarios where brender runs locally
+ * against a project directory (e.g. `smbls build --prerender`).
+ *
+ * For server runtime rendering, pass the project data
+ * directly to render() instead.
+ */
+export const loadProject = async (projectPath) => {
+  const symbolsDir = resolve(projectPath, 'symbols')
+
+  const [
+    appModule,
+    stateModule,
+    configModule,
+    depsModule,
+    componentsModule,
+    snippetsModule,
+    pagesModule,
+    functionsModule,
+    methodsModule,
+    designSystemModule,
+    filesModule,
+    assetsModule,
+    sharedLibsModule
+  ] = await Promise.all([
+    bundleAndImport(join(symbolsDir, 'app.js')),
+    bundleAndImport(join(symbolsDir, 'state.js')),
+    bundleAndImport(join(symbolsDir, 'config.js')),
+    bundleAndImport(join(symbolsDir, 'dependencies.js')),
+    bundleAndImport(join(symbolsDir, 'components', 'index.js')),
+    bundleAndImport(join(symbolsDir, 'snippets', 'index.js')),
+    bundleAndImport(join(symbolsDir, 'pages', 'index.js')),
+    bundleAndImport(join(symbolsDir, 'functions', 'index.js')),
+    bundleAndImport(join(symbolsDir, 'methods', 'index.js')),
+    bundleAndImport(join(symbolsDir, 'designSystem', 'index.js')),
+    bundleAndImport(join(symbolsDir, 'files', 'index.js')),
+    bundleAndImport(join(symbolsDir, 'assets', 'index.js')).catch(() => null),
+    bundleAndImport(join(symbolsDir, 'sharedLibraries.js')).catch(() => null)
+  ])
+
+  // Spread into plain objects — ESM module namespaces are non-extensible,
+  // which breaks downstream code that adds properties (e.g. polyglot functions).
+  const result = {
+    app: { ...(appModule?.default || {}) },
+    state: { ...(stateModule?.default || {}) },
+    dependencies: { ...(depsModule?.default || {}) },
+    components: { ...(componentsModule || {}) },
+    snippets: { ...(snippetsModule || {}) },
+    pages: { ...(pagesModule?.default || {}) },
+    functions: { ...(functionsModule || {}) },
+    methods: { ...(methodsModule || {}) },
+    designSystem: { ...(designSystemModule?.default || {}) },
+    files: { ...(filesModule?.default || {}) },
+    assets: { ...(assetsModule?.default || {}) },
+    config: { ...(configModule?.default || {}) },
+    sharedLibraries: sharedLibsModule?.default || []
+  }
+
+  // Pre-resolve string library references and merge into context
+  // so production builds have zero runtime overhead
+  if (result.sharedLibraries.length) {
+    const { resolveSharedLibraries, mergeSharedLibraries } = await import('@symbo.ls/utils')
+    const hasStrings = result.sharedLibraries.some(lib => typeof lib === 'string')
+    if (hasStrings) {
+      result.sharedLibraries = await resolveSharedLibraries(result.sharedLibraries)
+    }
+    mergeSharedLibraries(result, result.sharedLibraries)
+  }
+
+  return result
+}
+
+/**
+ * Renders all routes from a project directory and returns
+ * a map of route -> { html, metadata }.
+ * Useful for static prebuilding.
+ */
+export const loadAndRenderAll = async (projectPath, renderFn) => {
+  const data = await loadProject(projectPath)
+  const pages = data.pages || {}
+  const routes = Object.keys(pages)
+  const results = {}
+
+  for (const route of routes) {
+    results[route] = await renderFn(data, { route })
+  }
+
+  return results
+}

package/metadata.js

@@ -0,0 +1,5 @@
+/**
+ * Re-exports metadata utilities from the shared helmet plugin.
+ * Brender uses these for SSR head generation.
+ */
+export { extractMetadata, generateHeadHtml, resolveMetadata, applyMetadata } from '@symbo.ls/helmet'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@symbo.ls/brender",
-  "version": "3.14.7",
+  "version": "3.14.8",
   "license": "CC-BY-NC-4.0",
   "type": "module",
   "module": "./dist/esm/index.js",
@@ -25,6 +25,7 @@
   "source": "index.js",
   "files": [
     "dist",
+    "*.js",
     "*.md",
     "LICENSE"
   ],
@@ -40,8 +41,8 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@symbo.ls/css": "^3.14.9",
-    "@symbo.ls/helmet": "^3.14.7",
+    "@symbo.ls/css": "^3.14.10",
+    "@symbo.ls/helmet": "^3.14.8",
     "linkedom": "^0.16.8"
   },
   "devDependencies": {

package/prefetch.js

@@ -0,0 +1,363 @@
+/**
+ * SSR data prefetching for brender.
+ *
+ * Walks a page definition tree, collects `fetch` declarations,
+ * executes them against the configured DB adapter (e.g. Supabase),
+ * and returns the fetched data keyed by element path + `as` field.
+ *
+ * This allows brender to inject fetched data into element state
+ * before rendering, so the SSR output matches the client-side SPA.
+ */
+
+const isFunction = (v) => typeof v === 'function'
+const isArray = (v) => Array.isArray(v)
+const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v)
+
+/**
+ * Resolve a fetch config's params — if it's a function, call it with
+ * a mock element and state to get static params for SSR.
+ */
+const resolveParams = (params, mockState) => {
+  if (!params) return undefined
+  if (isFunction(params)) {
+    try {
+      // Build a mock element with basic call() support
+      const mockEl = {
+        state: mockState || {},
+        call: () => undefined,
+        __ref: {}
+      }
+      return params(mockEl, mockState || {})
+    } catch {
+      return undefined
+    }
+  }
+  return params
+}
+
+/**
+ * Normalize a single fetch declaration to a standard config object.
+ */
+const normalizeFetchConfig = (cfg, elementState) => {
+  if (!cfg) return null
+  if (typeof cfg === 'string') return { from: cfg, method: 'select' }
+
+  const resolved = isFunction(cfg) ? null : { ...cfg }
+  if (!resolved) return null
+
+  // Default method
+  if (!resolved.method) resolved.method = 'select'
+
+  // Resolve function params
+  if (isFunction(resolved.params)) {
+    resolved.params = resolveParams(resolved.params, elementState)
+  }
+
+  // Skip mutations and event-bound fetches
+  const isMutation = resolved.method === 'insert' || resolved.method === 'update' ||
+    resolved.method === 'upsert' || resolved.method === 'delete'
+  if (isMutation) return null
+  if (resolved.on && resolved.on !== 'create') return null
+
+  return resolved
+}
+
+/**
+ * Walk a page definition tree and collect all fetch declarations
+ * along with the path to the element's state.
+ *
+ * Returns: [{ config, stateKey, path, elementState }]
+ */
+const collectFetchDeclarations = (def, path = '') => {
+  if (!def || typeof def !== 'object') return []
+  // Skip function values and arrays of primitives
+  if (isFunction(def)) return []
+
+  const results = []
+  const elementState = def.state || {}
+
+  if (def.fetch) {
+    const fetchDefs = isArray(def.fetch) ? def.fetch : [def.fetch]
+    for (const fd of fetchDefs) {
+      const config = normalizeFetchConfig(fd, elementState)
+      if (config) {
+        results.push({
+          config,
+          stateKey: config.as,
+          path,
+          elementState
+        })
+      }
+    }
+  }
+
+  // Recurse into child elements (capitalized keys = child elements)
+  for (const key in def) {
+    if (key === 'fetch' || key === 'state' || key === 'props' ||
+        key === 'attr' || key === 'on' || key === 'define' ||
+        key === 'childExtends' || key === 'childProps' || key === 'childrenAs') continue
+    // Child elements have capitalized keys
+    if (key.charAt(0) >= 'A' && key.charAt(0) <= 'Z' && isObject(def[key])) {
+      results.push(...collectFetchDeclarations(def[key], path ? `${path}.${key}` : key))
+    }
+  }
+
+  return results
+}
+
+/**
+ * Create a Supabase adapter from project config for SSR use.
+ */
+const createSSRAdapter = async (dbConfig) => {
+  if (!dbConfig) return null
+
+  const { adapter, createClient, url, key, projectId } = dbConfig
+  if (adapter !== 'supabase') return null
+
+  const supabaseUrl = url || (projectId && `https://${projectId}.supabase.co`)
+  if (!supabaseUrl || !key) return null
+
+  // Always import @supabase/supabase-js for SSR — the serialized createClient
+  // from project data is a no-op placeholder that won't produce a real client.
+  let clientFactory
+  try {
+    const mod = await import('@supabase/supabase-js')
+    clientFactory = mod.createClient
+  } catch {
+    // Fall back to provided createClient only if import fails
+    clientFactory = createClient
+  }
+  if (!clientFactory) return null
+
+  const client = clientFactory(supabaseUrl, key)
+
+  return {
+    rpc: ({ from, params }) => client.rpc(from, params),
+    select: async ({ from, select: sel, params, limit, offset, order, single }) => {
+      let q = client.from(from).select(sel || '*')
+      if (params) {
+        for (const k in params) {
+          const v = params[k]
+          if (v === null) q = q.is(k, null)
+          else if (Array.isArray(v)) q = q.in(k, v)
+          else q = q.eq(k, v)
+        }
+      }
+      if (order) {
+        const orderBy = typeof order === 'string' ? order : order.by
+        q = q.order(orderBy, { ascending: order.asc !== false })
+      }
+      if (limit) q = q.limit(limit)
+      if (offset) q = q.range(offset, offset + (limit || 20) - 1)
+      if (single) q = q.single()
+      return q
+    }
+  }
+}
+
+/**
+ * Execute a single fetch config against the adapter.
+ * Returns the fetched data, or null on error.
+ */
+const executeSingle = async (adapter, config) => {
+  try {
+    const { method, from, params, transform, limit, offset, order, single } = config
+    let result
+
+    if (method === 'rpc') {
+      result = await adapter.rpc({ from, params })
+    } else {
+      result = await adapter.select({ from, select: config.select, params, limit, offset, order, single })
+    }
+
+    let data = result?.data ?? null
+    if (result?.error) {
+      return null
+    }
+
+    // Apply transform
+    if (data && transform && isFunction(transform)) {
+      try { data = transform(data) } catch { /* skip transform errors */ }
+    }
+
+    return data
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Prefetch all data for a page route.
+ *
+ * @param {object} data - Full project data (from loadProject)
+ * @param {string} route - Route to prefetch for (e.g. '/', '/blog')
+ * @param {object} [options]
+ * @returns {Promise<Map<string, object>>} Map of element path → { [stateKey]: data }
+ */
+export const prefetchPageData = async (data, route = '/', options = {}) => {
+  const pages = data.pages || {}
+  const pageDef = pages[route]
+  if (!pageDef) return new Map()
+
+  const config = data.config || data.settings || {}
+  const dbConfig = config.fetch || data.fetch || config.db || data.db
+  if (!dbConfig) return new Map()
+
+  const adapter = await createSSRAdapter(dbConfig)
+  if (!adapter) return new Map()
+
+  const declarations = collectFetchDeclarations(pageDef)
+  if (!declarations.length) return new Map()
+
+  const stateUpdates = new Map()
+
+  // Execute all fetches in parallel
+  const results = await Promise.allSettled(
+    declarations.map(async ({ config, stateKey, path }) => {
+      const fetchedData = await executeSingle(adapter, config)
+      if (fetchedData !== null) {
+        const existing = stateUpdates.get(path) || {}
+        if (stateKey) {
+          // Named: store under the `as` key
+          existing[stateKey] = fetchedData
+        } else if (isObject(fetchedData)) {
+          // No `as` key + transform returned an object: spread into state
+          Object.assign(existing, fetchedData)
+        }
+        stateUpdates.set(path, existing)
+      }
+    })
+  )
+
+  return stateUpdates
+}
+
+/**
+ * Inject prefetched data into a page definition's state objects.
+ * Mutates the definition in place (caller should deep-clone first).
+ *
+ * @param {object} pageDef - Page definition (will be mutated)
+ * @param {Map<string, object>} stateUpdates - Map from prefetchPageData
+ */
+/**
+ * Fetch polyglot translations from the DB for SSR use.
+ * Returns a map of { [lang]: { key: text, ... } } for all configured languages.
+ *
+ * @param {object} data - Full project data (from loadProject)
+ * @returns {Promise<object|null>} Translation map keyed by language, or null on failure
+ */
+export const fetchSSRTranslations = async (data) => {
+  // Config fields may be nested under data.config or spread at the top level
+  const config = data.config || {}
+  const polyglot = config.polyglot || data.polyglot
+  if (!polyglot?.fetch) return null
+
+  const dbConfig = config.fetch || data.fetch || config.db || data.db
+  if (!dbConfig) return null
+
+  const adapter = await createSSRAdapter(dbConfig)
+  if (!adapter) return null
+
+  const fetchConfig = polyglot.fetch
+  const rpcName = fetchConfig.rpc || fetchConfig.from || 'get_translations_if_changed'
+  const languages = polyglot.languages || [polyglot.defaultLang || 'en']
+
+  const translations = {}
+
+  // Fetch translations for all languages in parallel
+  const results = await Promise.allSettled(
+    languages.map(async (lang) => {
+      try {
+        const res = await adapter.rpc({
+          from: rpcName,
+          params: { p_lang: lang, p_cached_version: 0 }
+        })
+        if (res.error || !res.data) return
+        const result = res.data
+        if (result.translations) {
+          translations[lang] = result.translations
+        }
+      } catch (e) {
+        console.warn('[brender] SSR translation fetch failed:', e.message)
+      }
+    })
+  )
+
+  return Object.keys(translations).length ? translations : null
+}
+
+/**
+ * Pre-evaluate children functions and replace them with static results.
+ * During SSR, DOMQL's runtime state cascading and async re-render cycle
+ * may not work correctly (trackSourcemapDeep stack overflows, etc.).
+ * By pre-evaluating the children functions, we produce static element
+ * definitions that DOMQL can render directly.
+ */
+const preEvaluateChildren = (def, inheritedState) => {
+  if (!def || typeof def !== 'object') return
+  for (const key in def) {
+    if (key === 'state' || key === 'fetch' || key === 'props' ||
+        key === 'attr' || key === 'on' || key === 'define' ||
+        key === 'childExtends' || key === 'childProps' || key === 'childrenAs') continue
+    if (key.charAt(0) >= 'A' && key.charAt(0) <= 'Z' && isObject(def[key])) {
+      const child = def[key]
+      // Determine effective state for this element (own state or inherited)
+      const effectiveState = child.state && typeof child.state === 'object'
+        ? { ...inheritedState, ...child.state }
+        : inheritedState
+
+      // Pre-evaluate children function
+      if (isFunction(child.children)) {
+        try {
+          const mockEl = {
+            state: effectiveState,
+                call: (fn) => {
+              if (fn === 'getActiveLang' || fn === 'getLang') return effectiveState?.lang || 'ka'
+              if (fn === 'polyglot') return arguments[1] || ''
+              return undefined
+            },
+            __ref: {}
+          }
+          const result = child.children(mockEl, effectiveState)
+          if (isArray(result) && result.length > 0) {
+            // Replace children function with static array
+            child.children = result
+          }
+        } catch {
+          // If evaluation fails, leave the function as-is
+        }
+      }
+
+      // Recurse deeper
+      preEvaluateChildren(child, effectiveState)
+    }
+  }
+}
+
+export const injectPrefetchedState = (pageDef, stateUpdates) => {
+  if (!stateUpdates || !stateUpdates.size) return
+
+  for (const [path, data] of stateUpdates) {
+    // Navigate to the element at the path
+    let target = pageDef
+    if (path) {
+      const parts = path.split('.')
+      for (const part of parts) {
+        if (!target || typeof target !== 'object') break
+        target = target[part]
+      }
+    }
+
+    if (target && typeof target === 'object') {
+      // Merge fetched data into the element's state
+      if (!target.state || typeof target.state !== 'object') {
+        target.state = {}
+      }
+      Object.assign(target.state, data)
+
+      // Pre-evaluate children functions with the injected state
+      // so DOMQL gets static element definitions instead of functions
+      preEvaluateChildren(target, target.state)
+    }
+  }
+}