polen 0.11.0-next.15 → 0.11.0-next.17

package/src/types/virtual-modules.d.ts

@@ -3,37 +3,44 @@ declare module 'virtual:polen/vite/client/manifest' {
   export default manifest
 }
 
-declare module 'virtual:polen/template/variables' {
-  export const templateVariables: import('#api/config/configurator').TemplateVariables
-}
-
 declare module 'virtual:polen/project/routes.jsx' {
   export const routes: import('#vite/plugins/core').ProjectRoutesModule['routes']
 }
 
-declare module 'virtual:polen/template/schema-augmentations' {
-  export const schemaAugmentations: import('#api/schema/augmentations/schema-augmentation').Augmentation[]
+declare module 'virtual:polen/project/assets/logo.svg' {
+  const logo: {
+    light: string
+    dark: string
+    mode: 'single' | 'dual'
+    designedFor: 'light' | 'dark'
+  }
+  export default logo
 }
 
-declare module 'virtual:polen/project/data.json' {
-  const data: import('#project-data').ProjectData
-  export { data as default }
+declare module 'virtual:polen/project/assets/hero' {
+  const src: string | null
+  export default src
 }
 
-declare module 'virtual:polen/project/schema.json' {
-  // Object mapping filenames to JSON content for the catalog bridge
-  const schema: Record<string, string> | null
-  export { schema as default }
+declare module 'virtual:polen/project/schemas' {
+  export const schemasCatalog: import('#lib/catalog/$').Catalog.Catalog | null
 }
 
-declare module 'virtual:polen/project/data/pages-catalog.json' {
-  const data: import('#vite/plugins/pages').ProjectPagesCatalog
-  export { data as default }
+declare module 'virtual:polen/project/pages' {
+  export const pagesCatalog: import('#vite/plugins/pages').ProjectPagesCatalog
 }
 
-declare module 'virtual:polen/project/assets/logo.svg' {
-  const src: string
-  export default src
+declare module 'virtual:polen/project/examples' {
+  export const examplesCatalog: import('#api/examples/$').Examples.Catalog.Catalog
+  export const IndexComponent: React.ComponentType | null
+}
+
+declare module 'virtual:polen/project/config' {
+  export const templateConfig: import('#api/config-template/template').TemplateConfig
+}
+
+declare module 'virtual:polen/project/navbar' {
+  export const navbar: import('#api/content/navbar').NavbarItem[]
 }
 
 declare module 'virtual:polen/project/hooks' {

package/src/vite/config.ts

@@ -1,4 +1,4 @@
-import type { Api } from '#api/index'
+import type { Api } from '#api/$'
 import { Vite } from '#dep/vite/index'
 import { Main } from './plugins/main.js'
 

package/src/vite/logger.ts

@@ -1,12 +1,11 @@
-import type { Config } from '#api/api'
+import type { Api } from '#api/$'
 import { Vite } from '#dep/vite/index'
 import { Err, Str } from '@wollybeard/kit'
 import { stripAnsi } from 'consola/utils'
-import { onError } from 'effect/Stream'
 
 const baseLogger = Vite.createLogger(undefined)
 
-export const createLogger = (config: Config.Config): Vite.Logger => {
+export const createLogger = (config: Api.Config.Config): Vite.Logger => {
   return {
     ...baseLogger,
     info(msg, options) {

package/src/vite/plugins/branding.ts

@@ -1,12 +1,14 @@
-import type { Config } from '#api/api'
+import type { Api } from '#api/$'
 import type { Vite } from '#dep/vite/index'
 import { type ExistenceDiff, getMutationType, MutationType } from '#lib/mutation-type'
 import { debugPolen } from '#singletons/debug'
 import { Fs } from '@wollybeard/kit'
+import * as Path from 'node:path'
 import type { Plugin } from 'vite'
 import { polenVirtual } from '../vi.js'
 
 const viLogo = polenVirtual([`project`, `assets`, `logo.svg`])
+const viHero = polenVirtual([`project`, `assets`, `hero`])
 
 const generateDefaultLogo = async () => {
   return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 128 128" width="128" height="128">
@@ -14,40 +16,167 @@ const generateDefaultLogo = async () => {
 </svg>`
 }
 
-export function Branding(config: Config.Config): Plugin {
+const findLogoPath = async (publicDir: string, filename: string): Promise<string | null> => {
+  const extensions = ['svg', 'png', 'jpg', 'jpeg', 'webp']
+  for (const ext of extensions) {
+    const path = Path.join(publicDir, `${filename}.${ext}`)
+    if (await Fs.exists(path)) {
+      return path
+    }
+  }
+  return null
+}
+
+const findHeroImagePath = async (publicDir: string): Promise<string | null> => {
+  const heroImageNames = [
+    'hero.svg',
+    'hero.png',
+    'hero.jpg',
+    'hero.jpeg',
+    'hero.webp',
+  ]
+
+  for (const imageName of heroImageNames) {
+    const imagePath = Path.join(publicDir, imageName)
+    if (await Fs.exists(imagePath)) {
+      return imagePath
+    }
+  }
+
+  return null
+}
+
+export function Branding(config: Api.Config.Config): Plugin {
   const debug = debugPolen.sub(`vite-plugin:branding`)
   debug(`initialized`)
 
+  // Track logo paths and hero image path for watch/HMR
+  let logoLightPath: string | null = null
+  let logoDarkPath: string | null = null
+  let logoSinglePath: string | null = null
+  let currentHeroImagePath: string | null = null
+
   return {
     name: `polen:branding`,
     enforce: `pre`,
 
     async buildStart() {
+      // Check for logo files and add to watch
+      const publicDir = config.paths.project.absolute.public.root
+
+      // Check for dual mode (logo-light and logo-dark)
+      logoLightPath = await findLogoPath(publicDir, 'logo-light')
+      logoDarkPath = await findLogoPath(publicDir, 'logo-dark')
+
+      // Check for single mode (logo)
+      if (!logoLightPath || !logoDarkPath) {
+        logoSinglePath = await findLogoPath(publicDir, 'logo')
+      }
+
+      // Add logo files to watch
+      if (logoLightPath) this.addWatchFile(logoLightPath)
+      if (logoDarkPath) this.addWatchFile(logoDarkPath)
+      if (logoSinglePath) this.addWatchFile(logoSinglePath)
+      // Also watch the default logo path for compatibility
       this.addWatchFile(config.paths.project.absolute.public.logo)
+
+      // Watch for hero image files
+      const heroImagePath = await findHeroImagePath(config.paths.project.absolute.public.root)
+      if (heroImagePath) {
+        currentHeroImagePath = heroImagePath
+        this.addWatchFile(heroImagePath)
+      }
     },
 
     async handleHotUpdate({ file, server }) {
-      return await handleWatchedFileChange({
-        watchedFile: config.paths.project.absolute.public.logo,
-        changedFile: file,
-        moduleId: viLogo.resolved,
-        server,
-        debug: debug,
-      })
+      // Handle logo changes - check all possible logo files
+      if (
+        (logoLightPath && file === logoLightPath)
+        || (logoDarkPath && file === logoDarkPath)
+        || (logoSinglePath && file === logoSinglePath)
+        || file === config.paths.project.absolute.public.logo
+      ) {
+        // Invalidate the logo module when any logo file changes
+        const module = server.moduleGraph.getModuleById(viLogo.resolved)
+        if (module) {
+          server.moduleGraph.invalidateModule(module)
+          return []
+        }
+      }
+
+      // Handle hero image changes
+      if (currentHeroImagePath && file === currentHeroImagePath) {
+        return await handleWatchedFileChange({
+          watchedFile: currentHeroImagePath,
+          changedFile: file,
+          moduleId: viHero.resolved,
+          server,
+          debug: debug,
+        })
+      }
     },
 
     resolveId(id) {
       if (id === viLogo.id) {
         return viLogo.resolved
       }
+      if (id === viHero.id) {
+        return viHero.resolved
+      }
     },
 
     async load(id) {
       if (id === viLogo.resolved) {
-        const logoFileContent = await Fs.read(config.paths.project.absolute.public.logo)
-        const content = logoFileContent ? logoFileContent : await generateDefaultLogo()
+        const publicDir = config.paths.project.absolute.public.root
+
+        // Re-check for logos in case they changed
+        const lightPath = await findLogoPath(publicDir, 'logo-light')
+        const darkPath = await findLogoPath(publicDir, 'logo-dark')
+        const singlePath = await findLogoPath(publicDir, 'logo')
+
+        // Dual mode: both logo-light and logo-dark exist
+        if (lightPath && darkPath) {
+          const lightUrl = `/${Path.basename(lightPath)}`
+          const darkUrl = `/${Path.basename(darkPath)}`
+          return `export default {
+            light: ${JSON.stringify(lightUrl)},
+            dark: ${JSON.stringify(darkUrl)},
+            mode: 'dual',
+            designedFor: ${JSON.stringify(config.branding.logoDesignedFor)}
+          }`
+        }
+
+        // Single mode: only logo.* exists
+        if (singlePath) {
+          const url = `/${Path.basename(singlePath)}`
+          return `export default {
+            light: ${JSON.stringify(url)},
+            dark: ${JSON.stringify(url)},
+            mode: 'single',
+            designedFor: ${JSON.stringify(config.branding.logoDesignedFor)}
+          }`
+        }
+
+        // No logo files - use generated default
+        const content = await generateDefaultLogo()
         const dataUrl = `data:image/svg+xml;base64,${Buffer.from(content).toString(`base64`)}`
-        return `export default ${JSON.stringify(dataUrl)}`
+        return `export default {
+          light: ${JSON.stringify(dataUrl)},
+          dark: ${JSON.stringify(dataUrl)},
+          mode: 'single',
+          designedFor: 'light'
+        }`
+      }
+
+      if (id === viHero.resolved) {
+        const heroImagePath = await findHeroImagePath(config.paths.project.absolute.public.root)
+        if (heroImagePath) {
+          currentHeroImagePath = heroImagePath
+          // Just return the public URL path, let Vite handle the asset
+          const publicPath = `/${Path.basename(heroImagePath)}`
+          return `export default ${JSON.stringify(publicPath)}`
+        }
+        return `export default null`
       }
     },
   }

package/src/vite/plugins/build.ts

@@ -1,4 +1,4 @@
-import type { Api } from '#api/index'
+import type { Api } from '#api/$'
 import type { PolenBuildManifest } from '#api/static/manifest'
 import { Vite } from '#dep/vite/index'
 import { debugPolen } from '#singletons/debug'

package/src/vite/plugins/config.ts

@@ -0,0 +1,57 @@
+import type { Api } from '#api/$'
+import { encodeSyncTemplateConfig, resolve } from '#api/config-template/template'
+import type { Examples as ExamplesModule } from '#api/examples/$'
+import type { AssetReader } from '#lib/vite-reactive/reactive-asset-plugin'
+import { ViteVirtual } from '#lib/vite-virtual'
+import { debugPolen } from '#singletons/debug'
+import type { FileSystem } from '@effect/platform'
+import * as NodeFileSystem from '@effect/platform-node/NodeFileSystem'
+import { Effect } from 'effect'
+import type * as Vite from 'vite'
+import { polenVirtual } from '../vi.js'
+
+export const viProjectConfig = polenVirtual([`project`, `config`])
+
+export interface Options {
+  config: Api.Config.Config
+  schemaReader: AssetReader<Api.Schema.InputSource.LoadedCatalog | null, any, FileSystem.FileSystem>
+  examplesReader: AssetReader<ExamplesModule.ScanResult, any, FileSystem.FileSystem>
+}
+
+/**
+ * Config plugin that provides resolved template configuration
+ */
+export const Config = ({
+  config,
+  schemaReader,
+  examplesReader,
+}: Options): Vite.Plugin => {
+  const debug = debugPolen.sub(`vite-config`)
+
+  return {
+    name: 'polen:config-virtual',
+    ...ViteVirtual.IdentifiedLoader.toHooks({
+      identifier: viProjectConfig,
+      async loader() {
+        debug(`Loading viProjectConfig virtual module`)
+
+        // Load all catalogs
+        const loadedSchemaCatalog = await Effect.runPromise(
+          schemaReader.read().pipe(Effect.provide(NodeFileSystem.layer)),
+        )
+        const loadedExamplesCatalog = await Effect.runPromise(
+          examplesReader.read().pipe(Effect.provide(NodeFileSystem.layer)),
+        )
+
+        const templateConfig = resolve(config, {
+          // @claude todo: on loaded data structure, rename catalog to data
+          examples: loadedExamplesCatalog.catalog,
+          schemas: loadedSchemaCatalog?.data ?? undefined,
+        })
+
+        // @claude run decodeSync on the export
+        return `export const templateConfig = ${JSON.stringify(encodeSyncTemplateConfig(templateConfig))}`
+      },
+    }),
+  }
+}

package/src/vite/plugins/core.ts

@@ -1,48 +1,23 @@
-import { Content } from '#api/content/$'
-import { createNavbar, type NavbarItem } from '#api/content/navbar'
-import { Api } from '#api/index'
-import { Schema } from '#api/schema/$'
+import { Api } from '#api/$'
 import { VitePluginSelfContainedMode } from '#cli/_/self-contained-mode'
 import type { ReactRouter } from '#dep/react-router/index'
 import type { Vite } from '#dep/vite/index'
-import { Catalog } from '#lib/catalog/$'
-import { ViteVirtual } from '#lib/vite-virtual'
-import type { ProjectData } from '#project-data'
-import { debugPolen } from '#singletons/debug'
-import * as NodeFileSystem from '@effect/platform-node/NodeFileSystem'
 import { Json, Str } from '@wollybeard/kit'
-import { Effect } from 'effect'
 import { fileURLToPath } from 'node:url'
 import { polenVirtual } from '../vi.js'
-import { Pages } from './pages.js'
-import { SchemaAssets } from './schema-assets.js'
-
-const viTemplateVariables = polenVirtual([`template`, `variables`])
-const viTemplateSchemaAugmentations = polenVirtual([`template`, `schema-augmentations`])
-export const viProjectData = polenVirtual([`project`, `data.json`], { allowPluginProcessing: true })
-export const viProjectSchema = polenVirtual([`project`, `schema.json`], { allowPluginProcessing: true })
-export const viProjectHooks = polenVirtual([`project`, `hooks`], { allowPluginProcessing: true })
+import { Config as ConfigPlugin, viProjectConfig } from './config.js'
+import { Examples } from './examples.js'
+import { Hooks, viProjectHooks } from './hooks.js'
+import { Navbar, viProjectNavbar } from './navbar.js'
+import { Pages, viProjectRoutes } from './pages.js'
+import { Schemas, viProjectSchema } from './schemas.js'
 
 export interface ProjectRoutesModule {
   routes: ReactRouter.RouteObject[]
 }
 
 export const Core = (config: Api.Config.Config): Vite.PluginOption[] => {
-  let loadedCatalogCache: Api.Schema.InputSource.LoadedCatalog | null = null
-
-  const readSchema = async () => {
-    if (loadedCatalogCache === null) {
-      const loadedCatalog = await Effect.runPromise(
-        Schema.loadOrNull(config).pipe(
-          Effect.provide(NodeFileSystem.layer),
-        ),
-      )
-      loadedCatalogCache = loadedCatalog
-    }
-    return loadedCatalogCache
-  }
-
-  const plugins: Vite.Plugin[] = []
+  const conditionalPlugins: Vite.Plugin[] = []
 
   // Note: The main use for this right now is to resolve the react imports
   // from the mdx vite plugin which have to go through the Polen exports since Polen keeps those deps bundled.
@@ -50,14 +25,47 @@ export const Core = (config: Api.Config.Config): Vite.PluginOption[] => {
   // If we manage to get the mdx vite plugin that defers JSX transform to Rolldown then we can remove this!
   //
   if (config.advanced.isSelfContainedMode) {
-    plugins.push(VitePluginSelfContainedMode({
+    conditionalPlugins.push(VitePluginSelfContainedMode({
       projectDirPathExp: config.paths.project.rootDir,
     }))
   }
 
+  // Create all plugins with their self-contained readers
+  const schemasArea = Schemas({
+    config,
+    dependentVirtualModules: [viProjectConfig, viProjectNavbar],
+  })
+  const pagesArea = Pages({
+    config,
+    dependentVirtualModules: [viProjectNavbar, viProjectConfig, viProjectRoutes],
+  })
+  const examplesArea = Examples({
+    config,
+    schemaReader: schemasArea.reader,
+    dependentVirtualModules: [viProjectConfig, viProjectNavbar],
+  })
+  const configPlugin = ConfigPlugin({
+    config,
+    schemaReader: schemasArea.reader,
+    examplesReader: examplesArea.reader,
+  })
+  const navbarPlugin = Navbar({
+    config,
+    schemaReader: schemasArea.reader,
+    examplesReader: examplesArea.reader,
+    pagesReader: pagesArea.reader,
+  })
+
+  const hooksPlugin = Hooks({ config })
+
   return [
-    ...plugins,
-    SchemaAssets(config),
+    ...conditionalPlugins,
+    ...examplesArea.plugins,
+    ...schemasArea.plugins,
+    ...pagesArea.plugins,
+    configPlugin,
+    navbarPlugin,
+    hooksPlugin,
     /**
      * If a `polen*` import is encountered from the user's project, resolve it to the currently
      * running source code of Polen rather than the user's node_modules.
@@ -103,12 +111,12 @@ export const Core = (config: Api.Config.Config): Vite.PluginOption[] => {
         }
       },
     },
-    ...Pages({ config }),
     {
       name: `polen:core`,
       config(_, { command }) {
         return {
           root: config.paths.framework.rootDir,
+          publicDir: config.paths.project.absolute.public.root,
           // todo
           // future: {
           //   removePluginHookHandleHotUpdate: 'warn',
@@ -144,136 +152,6 @@ export const Core = (config: Api.Config.Config): Vite.PluginOption[] => {
           },
         }
       },
-      ...ViteVirtual.IdentifiedLoader.toHooks(
-        {
-          identifier: viProjectSchema,
-          async loader() {
-            const debug = debugPolen.sub(`module-project-schema`)
-            debug(`load`, { id: viProjectSchema.id })
-
-            const schemaResult = await readSchema()
-            if (!schemaResult || !schemaResult.data) {
-              return `export default null`
-            }
-
-            // Encode the catalog to convert GraphQLSchema to AST before serializing
-
-            const encodedCatalog = await Effect.runPromise(Catalog.encode(schemaResult.data))
-
-            return `export default ${JSON.stringify(encodedCatalog)}`
-          },
-        },
-        {
-          identifier: viTemplateVariables,
-          loader() {
-            const s = `export const templateVariables = ${JSON.stringify(config.templateVariables)}`
-            return s
-          },
-        },
-        {
-          identifier: viTemplateSchemaAugmentations,
-          loader() {
-            const s = `export const schemaAugmentations = ${JSON.stringify(config.schema?.augmentations ?? [])}`
-            return s
-          },
-        },
-        {
-          identifier: viProjectData,
-          async loader() {
-            const debug = debugPolen.sub(`module-project-data`)
-
-            debug(`load`, { id: viProjectData.id })
-
-            const loadedCatalog = await readSchema()
-
-            const navbar: NavbarItem[] = []
-
-            // ━ Schema presence causes adding some navbar items
-            if (loadedCatalog?.data) {
-              // IMPORTANT: Always ensure paths start with '/' for React Router compatibility.
-              // Without the leading slash, React Router treats paths as relative, which causes
-              // hydration mismatches between SSR (where base path is prepended) and client
-              // (where basename is configured). This ensures consistent behavior.
-              const referencePath = Api.Schema.Routing.createReferenceBasePath()
-              navbar.push({ pathExp: referencePath, title: `Reference`, position: 'left' })
-              // Check if we have revisions to show changelog
-              const catalog = loadedCatalog.data as Catalog.Catalog
-              const hasMultipleRevisions = Catalog.fold(
-                (versioned) => {
-                  // For versioned catalogs, count total revisions across all entries
-                  const totalRevisions = versioned.entries.reduce(
-                    (sum: number, entry) => sum + entry.revisions.length,
-                    0,
-                  )
-                  return totalRevisions > 1
-                },
-                (unversioned) => unversioned.schema.revisions?.length > 1,
-              )(catalog)
-
-              if (hasMultipleRevisions) {
-                navbar.push({ pathExp: `/changelog`, title: `Changelog`, position: 'right' })
-              }
-            }
-
-            //
-            // ━━ Scan pages and add to navbar
-            //
-
-            const pagesDir = config.paths.project.absolute.pages
-            const scanResult = await Effect.runPromise(
-              Content.scan({ dir: pagesDir }).pipe(
-                Effect.provide(NodeFileSystem.layer),
-              ),
-            )
-            const data = createNavbar(scanResult.list)
-            navbar.push(...data)
-
-            //
-            // ━━ Put It All together
-            //
-
-            const projectData: ProjectData = {
-              basePath: config.build.base,
-              paths: config.paths,
-              navbar, // Complete navbar with schema and pages
-              server: config.server,
-              warnings: config.warnings,
-            }
-
-            // Return a JavaScript module that exports the data
-            return `export default ${JSON.stringify(projectData)}`
-          },
-        },
-        {
-          identifier: viProjectHooks,
-          async loader() {
-            const fs = await import('node:fs/promises')
-            const path = await import('node:path')
-
-            const hooksPathTs = path.join(config.paths.project.rootDir, 'hooks.ts')
-            const hooksPathTsx = path.join(config.paths.project.rootDir, 'hooks.tsx')
-
-            let hooksPath = null
-            try {
-              await fs.access(hooksPathTsx)
-              hooksPath = hooksPathTsx
-            } catch {
-              try {
-                await fs.access(hooksPathTs)
-                hooksPath = hooksPathTs
-              } catch {
-                // No hooks file found
-              }
-            }
-
-            if (!hooksPath) {
-              return `export const navbar = null`
-            }
-
-            return `export * from '${hooksPath}'`
-          },
-        },
-      ),
     },
   ]
 }