polen 0.10.0-next.4 → 0.10.0-next.5

package/src/api/schema/data-sources/schema-directory/schema-directory.ts

@@ -1,7 +1,7 @@
 import { Grafaid } from '#lib/grafaid/index'
 import { GraphqlChange } from '#lib/graphql-change/index'
 import type { GraphqlChangeset } from '#lib/graphql-changeset/index'
-import { debug as debugPolen } from '#singletons/debug'
+import { debugPolen } from '#singletons/debug'
 import { Arr, Path } from '@wollybeard/kit'
 import { glob } from 'tinyglobby'
 import type { Schema } from '../../schema.ts'

package/src/api/vite/plugins/branding/index.ts

@@ -2,7 +2,7 @@ import type { Config } from '#api/api'
 import { polenVirtual } from '#api/vite/vi'
 import type { Vite } from '#dep/vite/index'
 import { type ExistenceDiff, getMutationType, MutationType } from '#lib/mutation-type'
-import { debug } from '#singletons/debug'
+import { debugPolen } from '#singletons/debug'
 import { Fs } from '@wollybeard/kit'
 import type { Plugin } from 'vite'
 
@@ -15,8 +15,8 @@ const generateDefaultLogo = async () => {
 }
 
 export function Branding(config: Config.Config): Plugin {
-  const _debug = debug.sub('vite-plugin:branding')
-  _debug('initialized')
+  const debug = debugPolen.sub('vite-plugin:branding')
+  debug('initialized')
 
   return {
     name: 'polen:branding',
@@ -32,7 +32,7 @@ export function Branding(config: Config.Config): Plugin {
         changedFile: file,
         moduleId: viLogo.resolved,
         server,
-        debug: _debug,
+        debug: debug,
       })
     },
 

package/src/api/vite/plugins/core.ts

@@ -6,7 +6,7 @@ import type { Vite } from '#dep/vite/index'
 import { VitePluginJson } from '#lib/vite-plugin-json/index'
 import { VitePluginReactiveData } from '#lib/vite-plugin-reactive-data/index'
 import { ViteVirtual } from '#lib/vite-virtual/index'
-import { debug } from '#singletons/debug'
+import { debugPolen } from '#singletons/debug'
 import { superjson } from '#singletons/superjson'
 import { Json, Str } from '@wollybeard/kit'
 import type { ProjectData } from '../../../project-data.ts'
@@ -16,7 +16,7 @@ import { createLogger } from '../logger.ts'
 import { polenVirtual } from '../vi.ts'
 import { Pages } from './pages.ts'
 
-const _debug = debug.sub(`vite-plugin-core`)
+const debug = debugPolen.sub(`vite-plugin-core`)
 
 const viTemplateVariables = polenVirtual([`template`, `variables`])
 const viTemplateSchemaAugmentations = polenVirtual([`template`, `schema-augmentations`])
@@ -87,7 +87,7 @@ export const Core = (config: Config.Config): Vite.PluginOption[] => {
       name: `polen:internal-import-alias`,
       enforce: 'pre' as const,
       resolveId(id, importer) {
-        const d = debug.sub(`vite-plugin:internal-import-alias`)
+        const d = debugPolen.sub(`vite-plugin:internal-import-alias`)
 
         const isPolenImporter = Boolean(
           importer
@@ -183,7 +183,7 @@ export const Core = (config: Config.Config): Vite.PluginOption[] => {
         {
           identifier: viProjectData,
           async loader() {
-            _debug(`loadingViProjectDataVirtualModule`)
+            debug(`loadingViProjectDataVirtualModule`)
             const schema = await readSchema()
 
             // ━ Schema presence causes adding some navbar items

package/src/api/vite/plugins/pages.ts

@@ -1,36 +1,37 @@
 import type { Config } from '#api/config/index'
+import { Content } from '#api/content/$'
 import type { NavbarDataRegistry } from '#api/vite/data/navbar'
 import { polenVirtual } from '#api/vite/vi'
 import type { Vite } from '#dep/vite/index'
 import { reportDiagnostics } from '#lib/file-router/diagnostic-reporter'
 import { FileRouter } from '#lib/file-router/index'
-import { Tree } from '#lib/tree/index'
-import { debug } from '#singletons/debug'
+import { debugPolen } from '#singletons/debug'
 import { superjson } from '#singletons/superjson'
 import mdx from '@mdx-js/rollup'
 import rehypeShiki from '@shikijs/rehype'
-import { Path, Str } from '@wollybeard/kit'
+import { Tree } from '@wollybeard/kit'
+import { Arr, Cache, Path, Str } from '@wollybeard/kit'
+import remarkFrontmatter from 'remark-frontmatter'
 import remarkGfm from 'remark-gfm'
 
-const _debug = debug.sub(`vite-plugin-pages`)
+const debug = debugPolen.sub(`vite-plugin-pages`)
 
 export const viProjectPages = polenVirtual([`project`, `pages.jsx`], { allowPluginProcessing: true })
 export const viProjectPagesData = polenVirtual([`project`, `data`, 'pages.jsonsuper'], { allowPluginProcessing: true })
 
-export interface PagesTreePluginOptions {
+export interface Options {
   config: Config.Config
   navbarData?: NavbarDataRegistry
-  onPagesChange?: (pages: FileRouter.ScanResult) => void
-  onTreeChange?: (tree: FileRouter.RouteTreeNode) => void
+  onChange?: (scanResult: Content.ScanResult) => void
 }
 
 export interface ProjectDataPages {
   sidebarIndex: SidebarIndex
-  pagesScanResult: FileRouter.ScanResult
+  pages: Content.Page[]
 }
 
 export interface SidebarIndex {
-  [pathExpression: string]: FileRouter.Sidebar.Sidebar
+  [pathExpression: string]: Content.Sidebar
 }
 
 /**
@@ -39,58 +40,22 @@ export interface SidebarIndex {
 export const Pages = ({
   config,
   navbarData,
-  onPagesChange,
-  onTreeChange,
-}: PagesTreePluginOptions): Vite.Plugin[] => {
-  let currentPagesData: FileRouter.ScanResult | null = null
-  let currentTreeData: FileRouter.RouteTreeNode | null = null
-
-  // State management
-  let pagesCache: FileRouter.ScanResult | null = null
-  let treeCache: FileRouter.RouteTreeNode | null = null
-
-  // Helper functions
-  const scanPages = async () => {
-    if (!pagesCache) {
-      _debug(`Scanning pages - cache is null, loading fresh data`)
-      pagesCache = await FileRouter.scan({
-        dir: config.paths.project.absolute.pages,
-        glob: `**/*.{md,mdx}`,
-      })
-      _debug(`Found ${String(pagesCache.routes.length)} pages`)
-    } else {
-      _debug(`Using cached pages`)
-    }
-    return pagesCache
-  }
-
-  const scanTree = async () => {
-    if (!treeCache) {
-      _debug(`Scanning tree - cache is null, loading fresh data`)
-      const result = await FileRouter.scanTree({
-        dir: config.paths.project.absolute.pages,
-        glob: `**/*.{md,mdx}`,
-      })
-      treeCache = result.routeTree
-      _debug(`Built route tree`)
-    } else {
-      _debug(`Using cached tree`)
-    }
-    return treeCache
-  }
-
-  const clearCache = () => {
-    _debug(`Clearing pages and tree cache`)
-    pagesCache = null
-    treeCache = null
-  }
+  onChange,
+}: Options): Vite.Plugin[] => {
+  const scanPages = Cache.memoize(debug.trace(async function scanPages() {
+    const result = await Content.scan({
+      dir: config.paths.project.absolute.pages,
+      glob: `**/*.{md,mdx}`,
+    })
+    return result
+  }))
 
   const isPageFile = (file: string) => {
     return (file.endsWith(`.md`) || file.endsWith(`.mdx`))
       && file.includes(config.paths.project.absolute.pages)
   }
 
-  const generatePagesModule = (pagesScanResult: FileRouter.ScanResult): string => {
+  const generatePagesModule = (pages: Content.Page[]): string => {
     const $ = {
       pages: `pages`,
     }
@@ -99,17 +64,21 @@ export const Pages = ({
     s`export const ${$.pages} = []`
 
     // Generate imports and route objects
-    for (const route of pagesScanResult.routes) {
+    for (const { route, metadata } of pages) {
       const filePathExp = Path.format(route.file.path.absolute)
       const pathExp = FileRouter.routeToPathExpression(route)
-      const ident = Str.Case.camel(`page ` + Str.titlizeSlug(pathExp))
+      const $$ = {
+        ...$,
+        Component: Str.Case.camel(`page ` + Str.titlizeSlug(pathExp)),
+      }
 
       s`
-        import ${ident} from '${filePathExp}'
+        import ${$$.Component} from '${filePathExp}'
 
-        ${$.pages}.push({
+        ${$$.pages}.push({
           path: '${pathExp}',
-          Component: ${ident}
+          Component: ${$$.Component},
+          metadata: ${JSON.stringify(metadata)}
         })
       `
     }
@@ -123,7 +92,11 @@ export const Pages = ({
       enforce: `pre` as const,
       ...mdx({
         jsxImportSource: `polen/react`,
-        remarkPlugins: [remarkGfm],
+        remarkPlugins: [
+          // Parse frontmatter blocks so they're removed from content
+          remarkFrontmatter,
+          remarkGfm,
+        ],
         rehypePlugins: [
           [
             rehypeShiki,
@@ -150,62 +123,58 @@ export const Pages = ({
       // Dev server configuration
       configureServer(server) {
         // Add pages directory to watcher
-        _debug(`configureServer: watch pages directory`, config.paths.project.absolute.pages)
+        debug(`configureServer: watch pages directory`, config.paths.project.absolute.pages)
         server.watcher.add(config.paths.project.absolute.pages)
       },
 
       // Hot update handling
       async handleHotUpdate({ file, server, modules }) {
-        _debug(`handleHotUpdate`, file)
+        debug(`handleHotUpdate`, file)
         if (!isPageFile(file)) return
 
-        _debug(`Page file changed:`, file)
+        debug(`Page file changed:`, file)
 
-        // Check if this is a content-only change to an existing page
-        const oldPages = pagesCache
+        // Get current pages before clearing cache
+        const oldPages = await scanPages()
 
         // Clear cache and rescan
-        clearCache()
-        const newPages = await scanPages()
-        currentPagesData = newPages
+        scanPages.clear()
+        const newScanResult = await scanPages()
 
         // Check if page structure changed (added/removed pages)
-        const structureChanged = !oldPages
-          || oldPages.routes.length !== newPages.routes.length
-          || !oldPages.routes.every((oldRoute, i) =>
-            oldRoute.file.path.absolute === newPages.routes[i]?.file.path.absolute
-          )
-
-        if (structureChanged) {
-          _debug(`Page structure changed, triggering full reload`)
-
-          // Invalidate virtual module
-          const mod = server.moduleGraph.getModuleById(viProjectPages.id)
-          if (mod) {
-            server.moduleGraph.invalidateModule(mod)
-            _debug(`Invalidated pages virtual module`)
-          }
+        const isJustContentChange = oldPages && !Arr.equalShallowly(
+          oldPages.list.map(p => Path.format(p.route.file.path.absolute)),
+          newScanResult.list.map(p => Path.format(p.route.file.path.absolute)),
+        )
 
-          // Notify about changes
-          if (onPagesChange) {
-            reportDiagnostics(newPages.diagnostics)
-            onPagesChange(newPages)
-          }
-
-          if (onTreeChange) {
-            const tree = await scanTree()
-            onTreeChange(tree)
-            currentTreeData = tree
-          }
-
-          // Trigger full reload for structure changes
-          server.ws.send({ type: `full-reload` })
-          return []
-        } else {
-          _debug(`Page content changed, allowing HMR`)
+        if (isJustContentChange) {
+          debug(`Page content changed, allowing HMR`)
           // Let default HMR handle the MDX file change
           return modules
         }
+
+        //
+        // ━━ Manual Invalidation
+        //
+
+        debug(`Page structure changed, triggering full reload`)
+
+        // Invalidate virtual module
+        const mod = server.moduleGraph.getModuleById(viProjectPages.id)
+        if (mod) {
+          server.moduleGraph.invalidateModule(mod)
+          debug(`Invalidated pages virtual module`)
+        }
+
+        // Notify about changes
+        if (onChange) {
+          reportDiagnostics(newScanResult.diagnostics)
+          onChange(newScanResult)
+        }
+
+        // Trigger full reload for structure changes
+        server.ws.send({ type: `full-reload` })
+        return []
       },
       resolveId(id) {
         if (id === viProjectPagesData.id) {
@@ -218,25 +187,13 @@ export const Pages = ({
         // },
         async handler(id) {
           if (id !== viProjectPagesData.resolved) return
-          _debug(`viProjectDataPages`)
-
-          // Get pages data from the pages plugin or load initially
-          if (!currentPagesData) {
-            _debug(`loadingPagesDataInitially`)
-            currentPagesData = await FileRouter.scan({
-              dir: config.paths.project.absolute.pages,
-              glob: `**/*.{md,mdx}`,
-            })
-            // Report any diagnostics from initial scan
-            reportDiagnostics(currentPagesData.diagnostics)
-          }
-          if (!currentTreeData) {
-            _debug(`loadingTreeDataInitially`)
-            currentTreeData = await getRouteTree(config)
-          }
-          const pagesScanResult = currentPagesData
-          const routeTree = currentTreeData
-          _debug(`usingPageRoutesFromPagesPlugin`, pagesScanResult.routes.length)
+          debug(`viProjectDataPages`)
+
+          const scanResult = await scanPages()
+
+          // Report any diagnostics
+          reportDiagnostics(scanResult.diagnostics)
+          debug(`Found ${String(scanResult.list.length)} visible pages`)
 
           //
           // ━━ Build Navbar
@@ -248,34 +205,26 @@ export const Pages = ({
             navbarPages.length = 0 // Clear existing
 
             // Process first-level children as navigation items
-            for (const child of routeTree.children) {
-              if (child.value.type === 'directory') {
-                // Check if this directory has an index file
-                const hasIndex = child.children.some(c => c.value.type === 'file' && c.value.name === 'index')
-
-                if (hasIndex) {
-                  const pathExp = FileRouter.pathToExpression([child.value.name])
-                  const title = Str.titlizeSlug(child.value.name)
+            if (scanResult.tree.root) {
+              for (const child of scanResult.tree.root.children) {
+                // Now we have Page objects in the tree
+                const page = child.value
+                const pathExp = FileRouter.routeToPathExpression(page.route)
+
+                // Skip hidden pages and index files at root level
+                if (page.metadata.hidden || page.route.logical.path.slice(-1)[0] === 'index') {
+                  continue
+                }
+
+                // Only include top-level pages (files directly in pages directory)
+                if (page.route.logical.path.length === 1) {
+                  const title = Str.titlizeSlug(page.route.logical.path[0]!)
                   navbarPages.push({
                     // 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.
                     pathExp: pathExp.startsWith('/') ? pathExp : '/' + pathExp,
                     title,
                   })
                 }
-              } else if (child.value.type === 'file' && child.value.name !== 'index') {
-                const pathExp = FileRouter.pathToExpression([child.value.name])
-                const title = Str.titlizeSlug(child.value.name)
-                navbarPages.push({
-                  // 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.
-                  pathExp: pathExp.startsWith('/') ? pathExp : '/' + pathExp,
-                  title,
-                })
               }
             }
           }
@@ -286,17 +235,25 @@ export const Pages = ({
 
           const sidebarIndex: SidebarIndex = {}
 
-          // Build sidebar for each top-level directory
-          for (const child of routeTree.children) {
-            if (child.value.type === 'directory') {
-              const pathExp = `/${child.value.name}`
-              // Create a subtree starting from this directory
-              const subtree = Tree.node(child.value, child.children)
-              // Pass the directory name as base path so paths are built correctly
-              const sidebar = FileRouter.Sidebar.buildFromTree(subtree, [child.value.name])
-              _debug(`Built sidebar for ${pathExp}:`, sidebar)
-              sidebarIndex[pathExp] = sidebar
-            }
+          // Build sidebar for each top-level directory using the page tree
+          if (scanResult.tree.root) {
+            Tree.visit(scanResult.tree, (node) => {
+              if (!node.value) return
+              const page = node.value as any
+              // Only process top-level directories (pages with logical path length > 1 indicate nested structure)
+              if (page.route.logical.path.length === 1 && node.children.length > 0) {
+                const topLevelDir = page.route.logical.path[0]!
+                const pathExp = `/${topLevelDir}`
+
+                // Create a subtree for this directory
+                const subtree = Tree.Tree(Tree.Node(page, node.children)) as Tree.Tree<any>
+
+                // Build sidebar using the new page tree builder
+                const sidebar = Content.buildFromPageTree(subtree, [topLevelDir])
+                debug(`Built sidebar for ${pathExp}:`, sidebar)
+                sidebarIndex[pathExp] = sidebar
+              }
+            })
           }
 
           //
@@ -305,7 +262,7 @@ export const Pages = ({
 
           const projectDataPages: ProjectDataPages = {
             sidebarIndex,
-            pagesScanResult: pagesScanResult,
+            pages: scanResult.list,
           }
 
           // Return just the JSON string - let the JSON plugin handle the transformation
@@ -313,7 +270,7 @@ export const Pages = ({
         },
       },
     },
-    // Plugin 4: Virtual Module for Pages Routes
+    // Plugin 3: Virtual Module for Pages Routes
     {
       name: 'polen:pages:routes',
       resolveId(id) {
@@ -328,17 +285,15 @@ export const Pages = ({
         handler: async (id) => {
           if (id !== viProjectPages.resolved) return
 
-          _debug(`Loading viProjectPages virtual module`)
+          debug(`Loading viProjectPages virtual module`)
 
-          // Ensure we have pages data
-          if (!currentPagesData) {
-            currentPagesData = await scanPages()
-            reportDiagnostics(currentPagesData.diagnostics)
-          }
+          const scanResult = await scanPages()
+          reportDiagnostics(scanResult.diagnostics)
+          const code = generatePagesModule(scanResult.list)
 
           // Generate the module code
           return {
-            code: generatePagesModule(currentPagesData),
+            code,
             moduleType: 'js',
           }
         },
@@ -346,12 +301,3 @@ export const Pages = ({
     },
   ]
 }
-
-// Helper to get tree
-export const getRouteTree = async (config: Config.Config): Promise<FileRouter.RouteTreeNode> => {
-  const result = await FileRouter.scanTree({
-    dir: config.paths.project.absolute.pages,
-    glob: `**/*.{md,mdx}`,
-  })
-  return result.routeTree
-}

package/src/api/vite/plugins/serve.ts

@@ -3,7 +3,7 @@ import { reportError } from '#api/server/report-error'
 import type { Hono } from '#dep/hono/index'
 import type { Vite } from '#dep/vite/index'
 import { ResponseInternalServerError } from '#lib/kit-temp'
-import { debug } from '#singletons/debug'
+import { debugPolen } from '#singletons/debug'
 import * as HonoNodeServer from '@hono/node-server'
 import { Err } from '@wollybeard/kit'
 
@@ -16,11 +16,11 @@ interface AppServerModule {
 export const Serve = (
   config: Config.Config,
 ): Vite.PluginOption => {
-  const _debug = debug.sub(`serve`)
+  const debug = debugPolen.sub(`serve`)
   let appPromise: Promise<App | Error>
 
   const reloadApp = async ({ server }: { server: Vite.ViteDevServer }): Promise<App | Error> => {
-    _debug('reloadApp')
+    debug('reloadApp')
     return server.ssrLoadModule(config.paths.framework.template.server.app)
       .then(module => module as AppServerModule)
       .then(module => module.app)
@@ -55,12 +55,12 @@ export const Serve = (
       }
     },
     handleHotUpdate({ server }) {
-      _debug('handleHotUpdate')
+      debug('handleHotUpdate')
       // Reload app server immediately in the background
       appPromise = reloadApp({ server })
     },
     async configureServer(server) {
-      _debug('configureServer')
+      debug('configureServer')
       // Initial load
       appPromise = reloadApp({ server })
 

package/src/cli/_/self-contained-mode.ts

@@ -1,7 +1,7 @@
 import type { Vite } from '#dep/vite/index'
 import { type ImportEvent, isSpecifierFromPackage } from '#lib/kit-temp'
 import { packagePaths } from '#package-paths'
-import { debug } from '#singletons/debug'
+import { debugPolen } from '#singletons/debug'
 import type * as Module from 'node:module'
 import { fileURLToPath } from 'node:url'
 
@@ -18,7 +18,7 @@ export function initialize(data: SelfContainedModeHooksData) {
 export const resolve: Module.ResolveHook = async (specifier, context, nextResolve) => {
   if (!data_) throw new Error(`Self-contained mode not initialized`)
 
-  const _debug = debug.sub(`node-module-hooks`)
+  const debug = debugPolen.sub(`node-module-hooks`)
 
   const from: ImportEvent = {
     specifier,
@@ -32,7 +32,7 @@ export const resolve: Module.ResolveHook = async (specifier, context, nextResolv
       importerPathExpOrFileUrlExp: from.context.parentURL,
     })
   ) {
-    _debug(`resolve check`, { specifier, context })
+    debug(`resolve check`, { specifier, context })
 
     const to: ImportEvent = {
       specifier: from.specifier,
@@ -43,7 +43,7 @@ export const resolve: Module.ResolveHook = async (specifier, context, nextResolv
       },
     }
 
-    _debug(`resolve`, { from, to })
+    debug(`resolve`, { from, to })
 
     await nextResolve(to.specifier, to.context)
   }
@@ -66,7 +66,7 @@ export const checkIsSelfImportFromProject = (input: {
 }
 
 export const VitePluginSelfContainedMode = ({ projectDirPathExp }: { projectDirPathExp: string }): Vite.Plugin => {
-  const d = debug.sub(`vite-plugin:self-contained-import`)
+  const d = debugPolen.sub(`vite-plugin:self-contained-import`)
 
   return {
     name: `polen:self-contained-import`,

package/src/exports/components.ts

@@ -0,0 +1 @@
+export * from '#template/components/content/$$'

package/src/lib/deployment/$$.ts

@@ -1,2 +1,2 @@
 export * from './metadata.ts'
-export * from './path-manager.ts'
+export * from './path-manager.ts'

package/src/lib/deployment/$.test.ts

@@ -26,7 +26,7 @@ describe('metadata', () => {
     }
 
     await Deployment.metadata.write(metadata, testDir)
-    
+
     const result = await Deployment.metadata.read(testDir)
     expect(result).toEqual(metadata)
   })
@@ -46,8 +46,8 @@ describe('metadata', () => {
     }
 
     await Deployment.metadata.write(metadata, testDir)
-    
+
     const fileExists = await Fs.exists(`${testDir}/.deployment.json`)
     expect(fileExists).toBe(true)
   })
-})
+})

package/src/lib/deployment/$.ts

@@ -1 +1 @@
-export * as Deployment from './$$.ts'
+export * as Deployment from './$$.ts'

package/src/lib/file-router/file-router.ts

@@ -1,5 +1,3 @@
 export * from './linter.ts'
 export * from './route.ts'
-export * from './scan-tree.ts'
 export * from './scan.ts'
-export * from './sidebar/index.ts'

package/src/lib/file-router/linter.test.ts

@@ -28,6 +28,8 @@ const createRoute = (path: string[], order?: number, isIndex = false): Route =>
         },
       },
     },
+    id: `/project/pages/${path.join('/')}/${name}.md`,
+    parentId: path.length > 1 ? `/project/pages/${path.slice(0, -1).join('/')}` : null,
   }
 }
 

package/src/lib/file-router/route.ts

@@ -36,6 +36,8 @@ export const pathToExpression = (path: Path) => {
 export interface Route {
   logical: RouteLogical
   file: RouteFile
+  id: string // Absolute file path for unique identification
+  parentId: string | null // Parent directory path, null for root-level files
 }
 
 export interface RouteLogical {