polen 0.9.0-next.6 → 0.9.0-next.8

package/src/api/schema/read.ts

@@ -6,7 +6,7 @@ export type DataSourceType = `file` | `directory` | `memory` | `data`
 
 export interface Config {
   /**
-   * @defaultValue `true`
+   * @default `true`
    */
   enabled?: boolean
   useDataSources?: Arr.Maybe<DataSourceType>

package/src/api/singletons/markdown/markdown.test.ts

@@ -12,7 +12,7 @@ console.log(x)
 \`\`\`
 `
     const result = await parse(markdown)
-    
+
     expect(result).toContain(`<h1>Hello</h1>`)
     expect(result).toContain(`<pre`)
     expect(result).toContain(`shiki`)
@@ -32,7 +32,7 @@ type Query {
 \`\`\`
 `
     const result = await parse(markdown)
-    
+
     expect(result).toContain(`type`)
     expect(result).toContain(`Query`)
     // Check that both ID and ! are present (they may be in separate spans)
@@ -43,7 +43,7 @@ type Query {
   test(`parse handles inline code`, async () => {
     const markdown = `This is \`inline code\` in a sentence.`
     const result = await parse(markdown)
-    
+
     expect(result).toContain(`<code>inline code</code>`)
   })
 
@@ -57,7 +57,7 @@ type Query {
 - [ ] Task 2
 `
     const result = await parse(markdown)
-    
+
     expect(result).toContain(`<table>`)
     expect(result).toContain(`<input`)
     expect(result).toContain(`checked`)
@@ -70,7 +70,7 @@ plain text without language
 \`\`\`
 `
     const result = await parse(markdown)
-    
+
     expect(result).toContain(`<pre`)
     expect(result).toContain(`plain text without language`)
   })
@@ -82,8 +82,8 @@ const theme = "light"
 \`\`\`
 `
     const result = await parse(markdown)
-    
+
     expect(result).toContain(`--shiki-light`)
     expect(result).toContain(`--shiki-dark`)
   })
-})
+})

package/src/api/singletons/markdown/markdown.ts

@@ -1,9 +1,9 @@
-import { unified } from 'unified'
-import remarkParse from 'remark-parse'
-import remarkGfm from 'remark-gfm'
-import remarkRehype from 'remark-rehype'
 import rehypeShiki from '@shikijs/rehype'
 import rehypeStringify from 'rehype-stringify'
+import remarkGfm from 'remark-gfm'
+import remarkParse from 'remark-parse'
+import remarkRehype from 'remark-rehype'
+import { unified } from 'unified'
 
 // Create a processor with Shiki for syntax highlighting (async only)
 const createProcessorWithShiki = () => {

package/src/api/utils/asset-url/asset-url.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, test } from 'vitest'
+import { assetUrl, faviconUrl, joinPaths, pageUrl } from './asset-url.js'
+
+describe('asset-url helpers', () => {
+  describe('joinPaths', () => {
+    test('joins base path with asset path', () => {
+      expect(joinPaths('/', 'assets/style.css')).toBe('/assets/style.css')
+      expect(joinPaths('/my-app/', 'assets/style.css')).toBe('/my-app/assets/style.css')
+      expect(joinPaths('/my-app/', '/assets/style.css')).toBe('/my-app/assets/style.css')
+    })
+
+    test('handles trailing slash in base', () => {
+      expect(joinPaths('/base/', 'path')).toBe('/base/path')
+    })
+
+    test('handles leading slash in path', () => {
+      expect(joinPaths('/base/', '/path')).toBe('/base/path')
+    })
+  })
+
+  describe('assetUrl', () => {
+    test('creates asset URLs with base path', () => {
+      expect(assetUrl('assets/app.js', '/')).toBe('/assets/app.js')
+      expect(assetUrl('assets/app.js', '/my-app/')).toBe('/my-app/assets/app.js')
+      expect(assetUrl('/assets/app.js', '/my-app/')).toBe('/my-app/assets/app.js')
+    })
+  })
+
+  describe('faviconUrl', () => {
+    test('creates favicon URLs with base path', () => {
+      expect(faviconUrl('logo.ico', '/')).toBe('/logo.ico')
+      expect(faviconUrl('logo.ico', '/my-app/')).toBe('/my-app/logo.ico')
+      expect(faviconUrl('/logo.ico', '/my-app/')).toBe('/my-app/logo.ico')
+    })
+  })
+
+  describe('pageUrl', () => {
+    test('creates page URLs with base path', () => {
+      expect(pageUrl('/', '/')).toBe('/')
+      expect(pageUrl('', '/')).toBe('/')
+      expect(pageUrl('/', '/my-app/')).toBe('/my-app/')
+      expect(pageUrl('', '/my-app/')).toBe('/my-app/')
+      expect(pageUrl('about', '/my-app/')).toBe('/my-app/about')
+      expect(pageUrl('/about', '/my-app/')).toBe('/my-app/about')
+    })
+  })
+})

package/src/api/utils/asset-url/asset-url.ts

@@ -0,0 +1,38 @@
+/**
+ * Helper functions for generating asset URLs that respect the base path configuration.
+ */
+
+/**
+ * Join a base path with an asset path, handling leading/trailing slashes correctly.
+ */
+export const joinPaths = (base: string, path: string): string => {
+  // Remove leading slash from path if present
+  const cleanPath = path.startsWith(`/`) ? path.slice(1) : path
+  // Base already has trailing slash by validation
+  return base + cleanPath
+}
+
+/**
+ * Create an asset URL from a path, respecting the base configuration.
+ */
+export const assetUrl = (path: string, base: string): string => {
+  return joinPaths(base, path)
+}
+
+/**
+ * Create a favicon URL from a path, respecting the base configuration.
+ */
+export const faviconUrl = (path: string, base: string): string => {
+  return assetUrl(path, base)
+}
+
+/**
+ * Create a page URL from a path, respecting the base configuration.
+ */
+export const pageUrl = (path: string, base: string): string => {
+  // For pages, we want to ensure no double slashes
+  if (path === `/` || path === ``) {
+    return base
+  }
+  return joinPaths(base, path)
+}

package/src/api/utils/asset-url/index.ts

@@ -0,0 +1 @@
+export * from './asset-url.ts'

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

@@ -190,9 +190,13 @@ export const Core = (config: Config.Config): Vite.PluginOption[] => {
             const schemaNavbar = navbarData.get('schema')
             schemaNavbar.length = 0 // Clear existing
             if (schema) {
-              schemaNavbar.push({ pathExp: `reference`, title: `Reference` })
+              // 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.
+              schemaNavbar.push({ pathExp: `/reference`, title: `Reference` })
               if (schema.versions.length > 1) {
-                schemaNavbar.push({ pathExp: `changelog`, title: `Changelog` })
+                schemaNavbar.push({ pathExp: `/changelog`, title: `Changelog` })
               }
             }
 
@@ -203,6 +207,7 @@ export const Core = (config: Config.Config): Vite.PluginOption[] => {
             const projectData: ProjectData = {
               schema,
               faviconPath: `/logo.svg`,
+              basePath: config.build.base,
               paths: config.paths.project,
               server: {
                 static: {
@@ -210,8 +215,9 @@ export const Core = (config: Config.Config): Vite.PluginOption[] => {
                   // relative from CWD of process that boots n1ode server
                   // can easily break! Use path relative in server??
                   directory: `./` + config.paths.project.relative.build.root,
-                  // Uses Hono route syntax.
-                  route: `/` + config.paths.project.relative.build.relative.assets + `/*`,
+                  // Uses Hono route syntax - includes base path
+                  route: config.build.base.slice(0, -1) + `/` + config.paths.project.relative.build.relative.assets
+                    + `/*`,
                 },
               },
             }

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

@@ -8,9 +8,9 @@ import { Tree } from '#lib/tree/index'
 import { debug } 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 remarkGfm from 'remark-gfm'
-import rehypeShiki from '@shikijs/rehype'
 
 const _debug = debug.sub(`vite-plugin-pages`)
 
@@ -257,7 +257,11 @@ export const Pages = ({
                   const pathExp = FileRouter.pathToExpression([child.value.name])
                   const title = Str.titlizeSlug(child.value.name)
                   navbarPages.push({
-                    pathExp: pathExp.startsWith('/') ? pathExp.slice(1) : pathExp,
+                    // 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,
                   })
                 }
@@ -265,7 +269,11 @@ export const Pages = ({
                 const pathExp = FileRouter.pathToExpression([child.value.name])
                 const title = Str.titlizeSlug(child.value.name)
                 navbarPages.push({
-                  pathExp: pathExp.startsWith('/') ? pathExp.slice(1) : pathExp,
+                  // 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,
                 })
               }

package/src/cli/commands/build.ts

@@ -11,6 +11,10 @@ const args = Command.create()
     `--architecture -a`,
     Api.Config.BuildArchitecture.default('ssg').describe('Which kind of application architecture to output.'),
   )
+  .parameter(
+    `--base -b`,
+    z.string().optional().describe('Base public path for deployment (e.g., /my-project/)'),
+  )
   .settings({
     parameters: {
       environment: {
@@ -33,4 +37,5 @@ const args = Command.create()
 await Api.Builder.build({
   ...(args.debug === false ? {} : { debug: args.debug }),
   ...(args.architecture === 'ssg' ? {} : { architecture: args.architecture }),
+  ...(args.base ? { base: args.base } : {}),
 })

package/src/cli/commands/dev.ts

@@ -14,6 +14,10 @@ const args = Command.create()
     // @ts-expect-error
     z.string().optional().describe(`The path to the project directory. Default is CWD (current working directory).`),
   )
+  .parameter(
+    `--base -b`,
+    z.string().optional().describe('Base public path for deployment (e.g., /my-project/)'),
+  )
   .settings({
     parameters: {
       environment: {
@@ -32,6 +36,7 @@ const dir = ensureOptionalAbsoluteWithCwd(args.project) as string
 const viteUserConfig = await Api.ConfigResolver.fromFile({
   dir,
   overrides: {
+    ...(args.base ? { build: { base: args.base } } : {}),
     advanced: {
       debug: args.debug,
     },

package/src/lib/shiki/index.ts

@@ -1 +1 @@
-export * from './shiki.ts'
+export * from './shiki.ts'

package/src/lib/shiki/shiki.ts

@@ -1,10 +1,10 @@
-import { createHighlighter, type Highlighter, type BundledTheme, type BundledLanguage } from 'shiki'
 import {
-  transformerNotationHighlight,
   transformerNotationDiff,
   transformerNotationFocus,
+  transformerNotationHighlight,
   transformerRenderWhitespace,
 } from '@shikijs/transformers'
+import { type BundledLanguage, type BundledTheme, createHighlighter, type Highlighter } from 'shiki'
 
 export interface ShikiOptions {
   themes?: {
@@ -88,7 +88,7 @@ export interface CodeHighlightOptions {
   theme?: 'light' | 'dark'
   showLineNumbers?: boolean
   highlightLines?: number[]
-  diffLines?: { add: number[], remove: number[] }
+  diffLines?: { add: number[]; remove: number[] }
   focusLines?: number[]
   showInvisibles?: boolean
 }
@@ -104,7 +104,7 @@ export async function highlightCode({
   showInvisibles = false,
 }: CodeHighlightOptions): Promise<string> {
   const highlighter = await getHighlighter()
-  
+
   const themes = {
     light: DEFAULT_THEMES.light,
     dark: DEFAULT_THEMES.dark,
@@ -119,7 +119,7 @@ export async function highlightCode({
       name: `line-numbers`,
       pre(node: any) {
         node.properties[`data-line-numbers`] = `true`
-      }
+      },
     })
   }
 
@@ -131,7 +131,7 @@ export async function highlightCode({
         if (highlightLines.includes(line)) {
           node.properties[`data-highlighted`] = `true`
         }
-      }
+      },
     })
   }
 
@@ -158,4 +158,4 @@ export async function highlightCode({
 }
 
 // Re-export types
-export type { Highlighter, BundledTheme, BundledLanguage } from 'shiki'
+export type { BundledLanguage, BundledTheme, Highlighter } from 'shiki'

package/src/lib/vite-virtual/identifier.ts

@@ -2,7 +2,7 @@ import { createId, markNoPlugins, normalizeId } from './id.ts'
 
 export interface Options {
   /**
-   * @defaultValue '/'
+   * @default '/'
    */
   separator?: string
   /**
@@ -10,7 +10,7 @@ export interface Options {
 
    * @see https://vitejs.dev/guide/api-plugin.html#virtual-modules-convention
 
-   * @defaultValue false
+   * @default false
    */
   allowPluginProcessing?: boolean
 }

package/src/project-data.ts

@@ -4,6 +4,7 @@ import type { Schema } from './api/schema/index.ts'
 export interface ProjectData {
   schema: null | Schema.Schema
   faviconPath: string
+  basePath: string
   paths: Config.Config[`paths`][`project`]
   server: {
     static: {

package/src/template/components/Link.tsx

@@ -52,11 +52,12 @@ export const getPathActiveReport = (
   // Normalize both paths for comparison
   const normalizedPath = pathExp.startsWith('/') ? pathExp.slice(1) : pathExp
   const normalizedCurrentPath = currentPathExp.startsWith('/') ? currentPathExp.slice(1) : currentPathExp
-  
+
   const isDirect = normalizedCurrentPath === normalizedPath
-  const isdescendant = normalizedCurrentPath.startsWith(normalizedPath + '/') && normalizedCurrentPath !== normalizedPath
+  const isdescendant = normalizedCurrentPath.startsWith(normalizedPath + '/')
+    && normalizedCurrentPath !== normalizedPath
   const is = isDirect || isdescendant
-  
+
   return {
     is,
     isDirect,

package/src/template/entry.client.tsx

@@ -6,6 +6,7 @@ import '@radix-ui/themes/styles.css'
 import { ReactDomClient } from '#dep/react-dom-client/index'
 import { StrictMode } from 'react'
 import { createBrowserRouter, RouterProvider } from 'react-router'
+import PROJECT_DATA from 'virtual:polen/project/data.jsonsuper'
 import { routes } from './routes.jsx'
 
 // SPA
@@ -20,6 +21,7 @@ import { routes } from './routes.jsx'
 
 const router = createBrowserRouter(routes, {
   hydrationData: window.__staticRouterHydrationData,
+  basename: PROJECT_DATA.basePath === `/` ? undefined : PROJECT_DATA.basePath.slice(0, -1), // Remove trailing slash for React Router
 })
 
 ReactDomClient.hydrateRoot(

package/src/template/routes/root.tsx

@@ -1,3 +1,4 @@
+import { assetUrl, faviconUrl } from '#api/utils/asset-url/index'
 import type { ReactRouter } from '#dep/react-router/index'
 import { createRoute } from '#lib/react-router-aid/react-router-aid'
 import { GitHubLogoIcon } from '@radix-ui/react-icons'
@@ -40,12 +41,12 @@ export const Component = () => {
         {import.meta.env.DEV && <link rel='stylesheet' href={radixStylesUrl} />}
         <link
           rel='icon'
-          href={PROJECT_DATA.faviconPath.replace(`.svg`, `.ico`) + `?v=1`}
+          href={faviconUrl(PROJECT_DATA.faviconPath.replace(`.svg`, `.ico`) + `?v=1`, PROJECT_DATA.basePath)}
           sizes='256 x 256'
         />
         <link
           rel='icon'
-          href={PROJECT_DATA.faviconPath + `?v=1`}
+          href={faviconUrl(PROJECT_DATA.faviconPath + `?v=1`, PROJECT_DATA.basePath)}
           sizes='any'
           type='image/svg+xml'
         />
@@ -120,7 +121,8 @@ const Layout = () => {
         my='8'
         mx='auto'
       >
-        <style>{`
+        <style>
+          {`
           /* Shiki code blocks */
           pre.shiki {
             margin: 1rem 0;
@@ -151,7 +153,8 @@ const Layout = () => {
             background: transparent;
             display: block;
           }
-        `}</style>
+        `}
+        </style>
         {header}
         {isShowSidebar && (
           <Sidebar

package/src/template/server/manifest.ts

@@ -1,25 +1,28 @@
+import { assetUrl } from '#api/utils/asset-url/index'
 import type { Vite } from '#dep/vite/index'
 import { Group, Str } from '@wollybeard/kit'
 
 export const injectManifestIntoHtml = (
   html: string,
   manifest: Vite.Manifest,
+  basePath: string,
 ): string => {
-  const assets = getRelevantAsssetsFromManifest(manifest)
+  const assets = getRelevantAsssetsFromManifest(manifest, basePath)
   return injectAssetsIntoHtml(html, assets)
 }
 
 const getRelevantAsssetsFromManifest = (
   manifest: Vite.Manifest,
+  basePath: string,
 ): HttpAssetGroupSet => {
   const htmlAssets: HttpAsset[] = []
 
   for (const manifestChunk of Object.values(manifest)) {
     if (manifestChunk.isEntry) {
-      htmlAssets.push({ type: `js`, path: `/${manifestChunk.file}` })
+      htmlAssets.push({ type: `js`, path: assetUrl(manifestChunk.file, basePath) })
     }
     for (const cssItem of manifestChunk.css ?? []) {
-      htmlAssets.push({ type: `css`, path: `/${cssItem}` })
+      htmlAssets.push({ type: `css`, path: assetUrl(cssItem, basePath) })
     }
   }
 

package/src/template/server/render-page.tsx

@@ -6,6 +6,7 @@ import { Arr } from '@wollybeard/kit'
 import { StrictMode } from 'react'
 import * as ReactDomServer from 'react-dom/server'
 import { createStaticRouter, StaticRouterProvider } from 'react-router'
+import PROJECT_DATA from 'virtual:polen/project/data.jsonsuper'
 import viteClientAssetManifest from 'virtual:polen/vite/client/manifest'
 import { injectManifestIntoHtml } from './manifest.ts'
 import { view } from './view.ts'
@@ -29,7 +30,7 @@ export const renderPage = (
   }
 
   if (__BUILDING__) {
-    html = injectManifestIntoHtml(html, viteClientAssetManifest)
+    html = injectManifestIntoHtml(html, viteClientAssetManifest, PROJECT_DATA.basePath)
   }
 
   // todo: what is this?

package/src/template/server/ssg/generate.ts

@@ -8,7 +8,22 @@ import { getRoutesPaths } from './get-route-paths.ts'
 
 export const generate = async (view: ReactRouter.StaticHandler) => {
   const handler: Hono.Handler = async (ctx) => {
-    const staticHandlerContext = await view.query(ctx.req.raw)
+    // For SSG, we need to create a request with the base path prepended
+    // so React Router can match it correctly
+    const url = new URL(ctx.req.raw.url)
+    const basePath = PROJECT_DATA.basePath === '/' ? '' : PROJECT_DATA.basePath.slice(0, -1)
+
+    // Create a new request with the base path prepended to the pathname
+    const modifiedRequest = new Request(
+      `${url.protocol}//${url.host}${basePath}${url.pathname}${url.search}`,
+      {
+        method: ctx.req.raw.method,
+        headers: ctx.req.raw.headers,
+        body: ctx.req.raw.body,
+      },
+    )
+
+    const staticHandlerContext = await view.query(modifiedRequest)
     if (staticHandlerContext instanceof Response) {
       return staticHandlerContext
     }
@@ -21,12 +36,60 @@ export const generate = async (view: ReactRouter.StaticHandler) => {
     app.get(routePath, handler)
   }
 
-  const result = await Hono.SSG.toSSG(app, NodeFs, {
-    concurrency: 10,
-    dir: PROJECT_DATA.paths.relative.build.root,
-  })
+  // For large schemas, we need to process in smaller batches to avoid memory issues
+  const BATCH_SIZE = 50
+  const totalPaths = routePaths.length
+  console.log(`[info] Generating ${totalPaths} static pages...`)
+
+  for (let i = 0; i < totalPaths; i += BATCH_SIZE) {
+    const batchPaths = routePaths.slice(i, i + BATCH_SIZE)
+    const batchApp = new Hono.Hono()
+
+    // Create a custom handler for batch processing that includes base path handling
+    const batchHandler: Hono.Handler = async (ctx) => {
+      // For SSG, we need to create a request with the base path prepended
+      const url = new URL(ctx.req.raw.url)
+      const basePath = PROJECT_DATA.basePath === '/' ? '' : PROJECT_DATA.basePath.slice(0, -1)
+
+      // Create a new request with the base path prepended to the pathname
+      const modifiedRequest = new Request(
+        `${url.protocol}//${url.host}${basePath}${url.pathname}${url.search}`,
+        {
+          method: ctx.req.raw.method,
+          headers: ctx.req.raw.headers,
+          body: ctx.req.raw.body,
+        },
+      )
+
+      const staticHandlerContext = await view.query(modifiedRequest)
+      if (staticHandlerContext instanceof Response) {
+        return staticHandlerContext
+      }
+      return renderPage(staticHandlerContext)
+    }
 
-  if (!result.success) {
-    throw new Error(`Failed to generate static site`, { cause: result.error })
+    // Register only the routes for this batch
+    for (const routePath of batchPaths) {
+      batchApp.get(routePath, batchHandler)
+    }
+
+    console.log(
+      `[info] Processing batch ${Math.floor(i / BATCH_SIZE) + 1}/${
+        Math.ceil(totalPaths / BATCH_SIZE)
+      } (${batchPaths.length} pages)...`,
+    )
+
+    const result = await Hono.SSG.toSSG(batchApp, NodeFs, {
+      concurrency: 5, // Reduced concurrency for memory efficiency
+      dir: PROJECT_DATA.paths.relative.build.root,
+    })
+
+    if (!result.success) {
+      throw new Error(`Failed to generate static site at batch ${Math.floor(i / BATCH_SIZE) + 1}`, {
+        cause: result.error,
+      })
+    }
   }
+
+  console.log(`[info] Successfully generated ${totalPaths} static pages.`)
 }

package/src/template/server/view.ts

@@ -1,4 +1,7 @@
 import { createStaticHandler } from 'react-router'
+import PROJECT_DATA from 'virtual:polen/project/data.jsonsuper'
 import { routes } from '../routes.jsx'
 
-export const view = createStaticHandler(routes)
+export const view = createStaticHandler(routes, {
+  basename: PROJECT_DATA.basePath === `/` ? undefined : PROJECT_DATA.basePath.slice(0, -1), // Remove trailing slash for React Router
+})