polen 0.11.0-next.12 → 0.11.0-next.14

package/src/api/iso/schema/validation.ts

@@ -1,4 +1,4 @@
-import { Grafaid } from '#lib/grafaid/index'
+import { Grafaid } from '#lib/grafaid'
 import type { GraphQLFieldMap, GraphQLSchema } from 'graphql'
 
 export interface PathValidation {

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

@@ -1,9 +1,9 @@
-import { Grafaid } from '#lib/grafaid/index'
-import { GraphqlChange } from '#lib/graphql-change/index'
-import type { GraphqlChangeset } from '#lib/graphql-changeset/index'
-import { GraphqlSchemaLoader } from '#lib/graphql-schema-loader/index'
+import { Grafaid } from '#lib/grafaid'
+import { GraphqlChange } from '#lib/graphql-change'
+import type { GraphqlChangeset } from '#lib/graphql-changeset'
+import { GraphqlSchemaLoader } from '#lib/graphql-schema-loader'
 import { Fs, Json, Path } from '@wollybeard/kit'
-import type { NonEmptyChangeSets, SchemaReadResult } from '../../schema.js'
+import type { SchemaReadResult } from '../../schema.js'
 
 /**
  * Configuration for loading schema via GraphQL introspection.
@@ -191,7 +191,9 @@ export const readOrThrow = async (
  * Create a single changeset from a schema object.
  * This is the core logic for handling single (unversioned) schemas from introspection.
  */
-export const createSingleSchemaChangeset = async (schema: Grafaid.Schema.Schema): Promise<NonEmptyChangeSets> => {
+export const createSingleSchemaChangeset = async (
+  schema: Grafaid.Schema.Schema,
+): Promise<GraphqlChangeset.ChangelogLinked> => {
   const date = new Date() // Generate date here for unversioned schema
   const after = schema
   const before = Grafaid.Schema.empty
@@ -200,14 +202,15 @@ export const createSingleSchemaChangeset = async (schema: Grafaid.Schema.Schema)
     after,
   })
 
-  const changeset: GraphqlChangeset.ChangeSet = {
+  const changeset: GraphqlChangeset.IntermediateChangeSetLinked = {
+    type: 'IntermediateChangeSet',
     date,
-    after,
-    before,
+    after: { version: null, data: after },
+    before: { version: null, data: before },
     changes,
   }
 
-  const result: NonEmptyChangeSets = [changeset]
+  const result: GraphqlChangeset.ChangelogLinked = [changeset]
 
   return result
 }

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

@@ -1,8 +1,7 @@
-import { Grafaid } from '#lib/grafaid/index'
-import { GraphqlChange } from '#lib/graphql-change/index'
-import type { GraphqlChangeset } from '#lib/graphql-changeset/index'
+import { Grafaid } from '#lib/grafaid'
+import { GraphqlChange } from '#lib/graphql-change'
+import type { GraphqlChangeset } from '#lib/graphql-changeset'
 import { Arr } from '@wollybeard/kit'
-import type { NonEmptyChangeSets } from '../../schema.js'
 
 /**
  * Configuration for defining schemas programmatically in memory.
@@ -68,7 +67,7 @@ export const normalize = (configInput: ConfigInput): Config => {
 
 export const read = async (
   configInput: ConfigInput,
-): Promise<null | NonEmptyChangeSets> => {
+): Promise<null | GraphqlChangeset.ChangelogLinked> => {
   const config = normalize(configInput)
 
   if (!Arr.isntEmpty(config.versions)) {
@@ -86,30 +85,41 @@ export const read = async (
 
   // todo: make DRY, this is same as for schema-directory
   const changesets = await Promise.all(
-    Arr.map(versions, async (version, index): Promise<GraphqlChangeset.ChangeSet> => {
+    Arr.map(versions, async (version, index): Promise<GraphqlChangeset.ChangeSetLinked> => {
       const current = version
       const previous = versions[index - 1]
 
       const before = previous?.schema ?? Grafaid.Schema.empty
       const after = current.schema
 
-      const changes = await GraphqlChange.calcChangeset({
-        before,
-        after,
-      })
+      if (!previous) {
+        // First version - create InitialChangeSet
+        return {
+          type: 'InitialChangeSet',
+          date: current.date,
+          after: { version: null, data: after },
+        }
+      } else {
+        // Subsequent versions - create IntermediateChangeSet
+        const changes = await GraphqlChange.calcChangeset({
+          before,
+          after,
+        })
 
-      return {
-        date: current.date,
-        before,
-        after,
-        changes,
+        return {
+          type: 'IntermediateChangeSet',
+          date: current.date,
+          before: { version: null, data: before },
+          after: { version: null, data: after },
+          changes,
+        }
       }
     }),
   )
 
   changesets.reverse()
 
-  const schema: NonEmptyChangeSets = changesets
+  const schema: GraphqlChangeset.ChangelogLinked = changesets
 
   return schema
 }

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

@@ -1,10 +1,9 @@
-import { Grafaid } from '#lib/grafaid/index'
-import { GraphqlChange } from '#lib/graphql-change/index'
-import type { GraphqlChangeset } from '#lib/graphql-changeset/index'
+import { Grafaid } from '#lib/grafaid'
+import { GraphqlChange } from '#lib/graphql-change'
+import type { GraphqlChangeset } from '#lib/graphql-changeset'
 import { debugPolen } from '#singletons/debug'
 import { Arr, Path } from '@wollybeard/kit'
 import { glob } from 'tinyglobby'
-import type { NonEmptyChangeSets } from '../../schema.js'
 import { readSingleSchemaFile } from '../schema-file/schema-file.js'
 import { FileNameExpression } from './file-name-expression/index.js'
 
@@ -71,7 +70,7 @@ export const normalizeConfig = (configInput: ConfigInput): Config => {
   return config
 }
 
-export const readOrThrow = async (configInput: ConfigInput): Promise<null | NonEmptyChangeSets> => {
+export const readOrThrow = async (configInput: ConfigInput): Promise<null | GraphqlChangeset.ChangelogLinked> => {
   const config = normalizeConfig(configInput)
 
   debug(`will search`, config)
@@ -124,7 +123,7 @@ export const readOrThrow = async (configInput: ConfigInput): Promise<null | NonE
  */
 const readVersionedSchemas = async (
   versionedExpressions: FileNameExpression.ExpressionVersioned[],
-): Promise<NonEmptyChangeSets> => {
+): Promise<GraphqlChangeset.ChangelogLinked> => {
   const versions = await Promise.all(Arr.map(versionedExpressions, async fileNameExpression => {
     const schemaFile = await Grafaid.Schema.read(fileNameExpression.filePath)
     // Should never happen since these paths come from the glob.
@@ -140,23 +139,34 @@ const readVersionedSchemas = async (
   versions.sort((a, b) => a.date.getTime() - b.date.getTime())
 
   const changesets = await Promise.all(
-    Arr.map(versions, async (version, index): Promise<GraphqlChangeset.ChangeSet> => {
+    Arr.map(versions, async (version, index): Promise<GraphqlChangeset.ChangeSetLinked> => {
       const current = version
       const previous = versions[index - 1]
 
       const before = previous?.schema ?? Grafaid.Schema.empty
       const after = current.schema
 
-      const changes = await GraphqlChange.calcChangeset({
-        before,
-        after,
-      })
-
-      return {
-        date: current.date,
-        before,
-        after,
-        changes,
+      if (!previous) {
+        // First version - create InitialChangeSet
+        return {
+          type: 'InitialChangeSet',
+          date: current.date,
+          after: { version: null, data: after },
+        }
+      } else {
+        // Subsequent versions - create IntermediateChangeSet
+        const changes = await GraphqlChange.calcChangeset({
+          before,
+          after,
+        })
+
+        return {
+          type: 'IntermediateChangeSet',
+          date: current.date,
+          before: { version: null, data: before },
+          after: { version: null, data: after },
+          changes,
+        }
       }
     }),
   )
@@ -164,5 +174,5 @@ const readVersionedSchemas = async (
   changesets.reverse()
 
   debug(`computed versioned schema`)
-  return changesets as NonEmptyChangeSets
+  return changesets as GraphqlChangeset.ChangelogLinked
 }

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

@@ -1,8 +1,7 @@
-import { Grafaid } from '#lib/grafaid/index'
-import { GraphqlChange } from '#lib/graphql-change/index'
-import type { GraphqlChangeset } from '#lib/graphql-changeset/index'
+import { Grafaid } from '#lib/grafaid'
+import { GraphqlChange } from '#lib/graphql-change'
+import type { GraphqlChangeset } from '#lib/graphql-changeset'
 import { Path } from '@wollybeard/kit'
-import type { NonEmptyChangeSets } from '../../schema.js'
 
 const defaultPaths = {
   schemaFile: `./schema.graphql`,
@@ -46,7 +45,7 @@ export const normalizeConfig = (configInput: ConfigInput): Config => {
 
 export const readOrThrow = async (
   configInput: ConfigInput,
-): Promise<null | NonEmptyChangeSets> => {
+): Promise<null | GraphqlChangeset.ChangelogLinked> => {
   const config = normalizeConfig(configInput)
 
   const schemaFile = await Grafaid.Schema.read(config.path)
@@ -59,7 +58,7 @@ export const readOrThrow = async (
  * Create a single changeset from a schema file path.
  * This is the core logic for handling single (unversioned) schemas.
  */
-export const readSingleSchemaFile = async (filePath: string): Promise<NonEmptyChangeSets> => {
+export const readSingleSchemaFile = async (filePath: string): Promise<GraphqlChangeset.ChangelogLinked> => {
   const schemaFile = await Grafaid.Schema.read(filePath)
   if (!schemaFile) throw new Error(`Failed to read schema file: ${filePath}`)
 
@@ -71,14 +70,15 @@ export const readSingleSchemaFile = async (filePath: string): Promise<NonEmptyCh
     after,
   })
 
-  const changeset: GraphqlChangeset.ChangeSet = {
+  const changeset: GraphqlChangeset.IntermediateChangeSetLinked = {
+    type: 'IntermediateChangeSet',
     date,
-    after,
-    before,
+    after: { version: null, data: after },
+    before: { version: null, data: before },
     changes,
   }
 
-  const schema: NonEmptyChangeSets = [changeset]
+  const schema: GraphqlChangeset.ChangelogLinked = [changeset]
 
   return schema
 }

package/src/api/schema/read.ts

@@ -1,6 +1,6 @@
-import { Arr, Fs, Path } from '@wollybeard/kit'
+import type { GraphqlChangeset } from '#lib/graphql-changeset'
+import { Arr } from '@wollybeard/kit'
 import * as DataSources from './data-sources/data-sources.js'
-import type { NonEmptyChangeSets } from './schema.js'
 
 export type DataSourceType =
   | `file`
@@ -15,7 +15,7 @@ export type DataSourceType =
  * Result of schema reading with provenance tracking for file watching and debugging.
  */
 export interface SchemaReadResult {
-  data: NonEmptyChangeSets | null
+  data: GraphqlChangeset.ChangelogLinked | null
   source: {
     type: DataSourceType
     /**
@@ -26,7 +26,7 @@ export interface SchemaReadResult {
      *
      * @returns Promise resolving to the recreated schema data, or null if recreation fails
      */
-    reCreate?: () => Promise<NonEmptyChangeSets | null>
+    reCreate?: () => Promise<GraphqlChangeset.ChangelogLinked | null>
   }
 }
 
@@ -121,7 +121,7 @@ export interface Config {
     /**
      * Pre-built schema object to use directly.
      */
-    data?: NonEmptyChangeSets
+    data?: GraphqlChangeset.ChangelogLinked
     /**
      * Configuration for loading schema via GraphQL introspection.
      *

package/src/api/schema/schema.ts

@@ -1,5 +1,3 @@
-import type { GraphqlChangeset } from '#lib/graphql-changeset/index'
-
 // Re-export everything from isomorphic layer
 export * from '../iso/schema/constants.js'
 export * as Routing from '../iso/schema/routing.js'
@@ -8,15 +6,3 @@ export * as Routing from '../iso/schema/routing.js'
 export * as DataSources from './data-sources/data-sources.js'
 export * from './metadata.js'
 export * from './read.js'
-
-export type ChangeSets = GraphqlChangeset.ChangeSet[]
-
-export type NonEmptyChangeSets = [GraphqlChangeset.ChangeSet, ...GraphqlChangeset.ChangeSet[]]
-
-/**
- * Changelog data structure for JSON serialization
- */
-export interface ChangelogData {
-  changes: GraphqlChangeset.ChangeSet['changes']
-  date: string
-}

package/src/api/schema-augmentation/augmentations/description.ts

@@ -1,4 +1,4 @@
-import type { GrafaidOld } from '#lib/grafaid-old/index'
+import type { GrafaidOld } from '#lib/grafaid-old'
 import { neverCase } from '@wollybeard/kit/language'
 import type { Target } from '../target.js'
 import { locateTargetField, locateTargetType } from '../target.js'

package/src/api/schema-augmentation/schema-augmentation.ts

@@ -1,4 +1,4 @@
-import type { GrafaidOld } from '#lib/grafaid-old/index'
+import type { GrafaidOld } from '#lib/grafaid-old'
 import { neverCase } from '@wollybeard/kit/language'
 import * as AugmentationDescription from './augmentations/description.js'
 

package/src/api/schema-augmentation/target.ts

@@ -1,4 +1,4 @@
-import { Grafaid } from '#lib/grafaid/index'
+import { Grafaid } from '#lib/grafaid'
 
 export type Target = TargetType | TargetField
 

package/src/api/schema-source/schema-source.ts

@@ -1,6 +1,7 @@
 import { Schema } from '#api/schema/index'
-import { Grafaid } from '#lib/grafaid/index'
-import type { GraphqlChangeset } from '#lib/graphql-changeset/index'
+import { Grafaid } from '#lib/grafaid'
+import { GraphqlChangeset } from '#lib/graphql-changeset'
+import { SchemaLifecycle } from '#lib/schema-lifecycle'
 import { astToSchema } from '#template/lib/schema-utils/schema-utils'
 import { Cache } from '@wollybeard/kit'
 import type { GraphQLSchema } from 'graphql'
@@ -34,17 +35,20 @@ interface SchemaSourceConfig {
   }
   versions: string[]
   assetsPath: string
+  debug?: boolean
 }
 
 export const createSchemaSource = (config: SchemaSourceConfig) => {
   const getSchemaPath = (version: string) => `${config.assetsPath}/schemas/${version}.json`
 
-  const getChangelogPath = (version: string) => `${config.assetsPath}/schemas/${version}.changelog.json`
+  const getChangelogPath = (version: string) => `${config.assetsPath}/schemas/${version}.release.changelog.json`
 
   const getSchemasDirectory = () => `${config.assetsPath}/schemas`
 
   const getMetadataPath = () => `${config.assetsPath}/schemas/metadata.json`
 
+  const getLifecyclePath = () => `${config.assetsPath}/schemas/lifecycle.json`
+
   const ioWrite = config.io.write || NoImplementationWriteFile
   const ioClearDirectory = config.io.clearDirectory || NoImplementationClearDirectory
   const ioRemoveFile = config.io.removeFile || NoImplementationRemoveFile
@@ -59,12 +63,12 @@ export const createSchemaSource = (config: SchemaSourceConfig) => {
     return schema
   }
 
-  const getChangelog = async (version: string): Promise<Schema.ChangelogData> => {
+  const getChangelog = async (version: string): Promise<GraphqlChangeset.ChangeSet> => {
     const content = await ioReadMemoized(getChangelogPath(version))
-    return JSON.parse(content)
+    return GraphqlChangeset.fromJson(content)
   }
 
-  const getAllChangesets = async (): Promise<GraphqlChangeset.ChangeSet[]> => {
+  const getAllChangesets = async (): Promise<GraphqlChangeset.Changelog> => {
     const changesets: GraphqlChangeset.ChangeSet[] = []
 
     for (let i = 0; i < config.versions.length; i++) {
@@ -82,28 +86,33 @@ export const createSchemaSource = (config: SchemaSourceConfig) => {
 
       if (changelogData) {
         const prevVersion = config.versions[i + 1]
-        const prevSchema = prevVersion ? await get(prevVersion) : null
 
-        if (prevSchema) {
+        if (prevVersion) {
+          const prevSchema = await get(prevVersion)
           changesets.push({
-            after: schema,
-            before: prevSchema,
-            changes: changelogData.changes,
+            type: 'IntermediateChangeSet',
+            after: { data: schema, version },
+            before: { data: prevSchema, version: prevVersion },
+            changes: GraphqlChangeset.isIntermediateChangeSet(changelogData) ? changelogData.changes : [],
             date: new Date(changelogData.date),
           })
         }
       } else {
         // Oldest version - no changelog, use existing utility
         changesets.push({
-          after: schema,
-          before: Grafaid.Schema.empty,
-          changes: [],
+          type: 'InitialChangeSet',
           date: Schema.versionStringToDate(version),
+          after: { data: schema, version },
         })
       }
     }
 
-    return changesets
+    return changesets as GraphqlChangeset.Changelog
+  }
+
+  const getLifecycle = async (): Promise<SchemaLifecycle.SchemaLifecycle> => {
+    const content = await ioReadMemoized(getLifecyclePath())
+    return SchemaLifecycle.fromJson(content)
   }
 
   return {
@@ -119,6 +128,7 @@ export const createSchemaSource = (config: SchemaSourceConfig) => {
     get,
     getChangelog,
     getAllChangesets,
+    getLifecycle,
 
     // Expose the memoized reader's clear method
     clearCache: ioReadMemoized.clear,
@@ -129,8 +139,15 @@ export const createSchemaSource = (config: SchemaSourceConfig) => {
       await ioWrite(getSchemaPath(version), JSON.stringify(ast))
     },
 
-    writeChangelog: async (version: string, changelog: Schema.ChangelogData) => {
-      await ioWrite(getChangelogPath(version), JSON.stringify(changelog))
+    writeChangelog: async (version: string, changelog: GraphqlChangeset.ChangeSet) => {
+      await ioWrite(
+        getChangelogPath(version),
+        GraphqlChangeset.toJson(changelog),
+      )
+    },
+
+    writeLifecycle: async (lifecycle: SchemaLifecycle.SchemaLifecycle) => {
+      await ioWrite(getLifecyclePath(), SchemaLifecycle.toJson(lifecycle))
     },
 
     // Directory operations
@@ -157,33 +174,43 @@ export const createSchemaSource = (config: SchemaSourceConfig) => {
     },
 
     writeAllAssets: async (
-      schemaData: Awaited<ReturnType<typeof Schema.readOrThrow>>['data'],
+      changelog: GraphqlChangeset.Changelog,
       metadata: Schema.SchemaMetadata,
+      lifecycle?: SchemaLifecycle.SchemaLifecycle,
     ) => {
-      if (!schemaData) return
+      if (!changelog) return
 
       // Write schema and changelog files
-      for (const [index, version] of schemaData!.entries()) {
-        const versionName = index === 0 ? Schema.VERSION_LATEST : Schema.dateToVersionString(version.date)
+      for (const [index, changeset] of changelog.entries()) {
+        const versionName = index === 0 ? Schema.VERSION_LATEST : Schema.dateToVersionString(changeset.date)
 
         // Write schema file
-        await ioWrite(
-          getSchemaPath(versionName),
-          JSON.stringify(Grafaid.Schema.AST.parse(Grafaid.Schema.print(version.after))),
-        )
+        if (changeset.after?.data) {
+          await ioWrite(
+            getSchemaPath(versionName),
+            JSON.stringify(Grafaid.Schema.AST.parse(Grafaid.Schema.print(changeset.after.data))),
+          )
+        }
 
-        // Write changelog file (except for the oldest/last version)
-        if (Schema.shouldVersionHaveChangelog(index, schemaData!.length)) {
-          const changelogData = {
-            changes: version.changes,
-            date: version.date.toISOString(),
-          }
-          await ioWrite(getChangelogPath(versionName), JSON.stringify(changelogData))
+        // Write changelog file only for intermediate changesets
+        if (GraphqlChangeset.isIntermediateChangeSet(changeset)) {
+          await ioWrite(
+            getChangelogPath(versionName),
+            GraphqlChangeset.toJson(changeset),
+          )
         }
       }
 
       // Write metadata file
       await ioWrite(getMetadataPath(), JSON.stringify(metadata, null, 2))
+
+      // Write lifecycle file if provided
+      if (lifecycle) {
+        await ioWrite(
+          getLifecyclePath(),
+          SchemaLifecycle.toJson(lifecycle),
+        )
+      }
     },
   }
 }

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

@@ -1,7 +1,7 @@
 import type { Config } from '#api/config/index'
 import type { PolenBuildManifest } from '#api/static/manifest'
 import { Vite } from '#dep/vite/index'
-import { ViteVirtual } from '#lib/vite-virtual/index'
+import { ViteVirtual } from '#lib/vite-virtual'
 import { debugPolen } from '#singletons/debug'
 import { Fs, Path } from '@wollybeard/kit'
 import packageJson from '../../../../package.json' with { type: 'json' }

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

@@ -1,15 +1,16 @@
 import type { Config } from '#api/config/index'
 import { Content } from '#api/content/$'
-import { createNavbar } from '#api/content/navbar'
+import { createNavbar, type NavbarItem } from '#api/content/navbar'
 import { Api } from '#api/index'
 import { VitePluginSelfContainedMode } from '#cli/_/self-contained-mode'
 import type { ReactRouter } from '#dep/react-router/index'
 import type { Vite } from '#dep/vite/index'
-import { VitePluginJson } from '#lib/vite-plugin-json/index'
-import { ViteVirtual } from '#lib/vite-virtual/index'
+import { VitePluginJson } from '#lib/vite-plugin-json'
+import { ViteVirtual } from '#lib/vite-virtual'
 import { debugPolen } from '#singletons/debug'
 import { superjson } from '#singletons/superjson'
 import { Json, Str } from '@wollybeard/kit'
+import { fileURLToPath } from 'node:url'
 import type { ProjectData } from '../../../project-data.js'
 import { SchemaAugmentation } from '../../schema-augmentation/index.js'
 import { Schema } from '../../schema/index.js'
@@ -21,6 +22,7 @@ const viTemplateVariables = polenVirtual([`template`, `variables`])
 const viTemplateSchemaAugmentations = polenVirtual([`template`, `schema-augmentations`])
 export const viProjectData = polenVirtual([`project`, `data.jsonsuper`], { allowPluginProcessing: true })
 export const viProjectSchema = polenVirtual([`project`, `schema.jsonsuper`], { allowPluginProcessing: true })
+export const viProjectHooks = polenVirtual([`project`, `hooks`], { allowPluginProcessing: true })
 
 export interface ProjectRoutesModule {
   routes: ReactRouter.RouteObject[]
@@ -37,7 +39,9 @@ export const Core = (config: Config.Config): Vite.PluginOption[] => {
       })
       // todo: augmentations scoped to a version
       schemaResult.data?.forEach(version => {
-        SchemaAugmentation.apply(version.after, config.schemaAugmentations)
+        if (version.after) {
+          SchemaAugmentation.apply(version.after.data, config.schemaAugmentations)
+        }
       })
       schemaCache = schemaResult
     }
@@ -60,7 +64,7 @@ export const Core = (config: Config.Config): Vite.PluginOption[] => {
   const jsonsuper = VitePluginJson.create({
     codec: {
       validate: superjson,
-      importPath: import.meta.resolve(`#singletons/superjson`),
+      importPath: `#singletons/superjson`,
       importExport: `superjson`,
     },
     filter: {
@@ -104,10 +108,16 @@ export const Core = (config: Config.Config): Vite.PluginOption[] => {
         const match = Str.match(id, find)
         if (!match) return null
 
-        const to = `${config.paths.framework.sourceDir}/${match.groups.path}${config.paths.framework.sourceExtension}`
-        // debug(`did resolve`, { from: id, to })
-
-        return to
+        // Use Node's resolver to handle package.json imports correctly
+        try {
+          const resolved = import.meta.resolve(id)
+          const to = fileURLToPath(resolved)
+          // debug(`did resolve`, { from: id, to })
+          return to
+        } catch {
+          // If resolution fails, return null to let other resolvers handle it
+          return null
+        }
       },
     },
     jsonsuper,
@@ -189,7 +199,7 @@ export const Core = (config: Config.Config): Vite.PluginOption[] => {
 
             const schemaResult = await readSchema()
 
-            const navbar = []
+            const navbar: NavbarItem[] = []
 
             // ━ Schema presence causes adding some navbar items
             if (schemaResult.data) {
@@ -198,9 +208,9 @@ export const Core = (config: Config.Config): Vite.PluginOption[] => {
               // 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` })
+              navbar.push({ pathExp: referencePath, title: `Reference`, position: 'left' })
               if (schemaResult.data.length > 1) {
-                navbar.push({ pathExp: `/changelog`, title: `Changelog` })
+                navbar.push({ pathExp: `/changelog`, title: `Changelog`, position: 'right' })
               }
             }
 
@@ -229,6 +239,35 @@ export const Core = (config: Config.Config): Vite.PluginOption[] => {
             return superjson.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}'`
+          },
+        },
       ),
     },
   ]

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

@@ -2,8 +2,8 @@ import type { Config } from '#api/config/index'
 import { Content } from '#api/content/$'
 import { polenVirtual } from '#api/vite/vi'
 import type { Vite } from '#dep/vite/index'
+import { FileRouter } from '#lib/file-router'
 import { reportDiagnostics } from '#lib/file-router/diagnostic-reporter'
-import { FileRouter } from '#lib/file-router/index'
 import { debugPolen } from '#singletons/debug'
 import { superjson } from '#singletons/superjson'
 import mdx from '@mdx-js/rollup'