@karaoke-cms/astro 0.6.3 → 0.9.0

package/README.md

@@ -0,0 +1,94 @@
+# @karaoke-cms/astro
+
+Core Astro integration for karaoke-cms. Every karaoke-cms project depends on this package.
+
+## Where it belongs
+
+`packages/astro/` in the monorepo. Users install it as a dependency and register it in `astro.config.mjs`:
+
+```js
+// astro.config.mjs
+import { defineConfig } from 'astro/config';
+import karaoke from '@karaoke-cms/astro';
+import karaokeConfig from './karaoke.config.ts';
+
+export default defineConfig({
+  site: 'https://your-site.pages.dev',
+  integrations: [karaoke(karaokeConfig)],
+});
+```
+
+## What it does
+
+`karaoke(config)` is an Astro integration that wires up the full karaoke-cms runtime at build time:
+
+- **Loads the active theme** as a nested Astro integration (resolves by package name from `config.theme`)
+- **Injects core routes**: `/rss.xml` always; `/karaoke-cms` and `/karaoke-cms/[...slug]` in dev mode only
+- **Exposes a virtual module** (`virtual:karaoke-cms/config`) with all resolved config — title, description, collections, menus, layout, modules
+- **Registers wikilinks** via `remark-wiki-link` (`[[note]]` → `/note/`, `[[note|text]]` with alias)
+- **Registers sitemap** via `@astrojs/sitemap`
+
+### Virtual module
+
+Every page and component in the framework reads config from `virtual:karaoke-cms/config`:
+
+```ts
+import {
+  siteTitle,          // string
+  siteDescription,    // string
+  resolvedCollections, // Record<string, ResolvedCollection>
+  resolvedMenus,      // Record<string, ResolvedMenu>
+  resolvedLayout,     // { regions: { top, left, right, bottom } }
+  resolvedModules,    // { search: { enabled }, comments: { enabled, ... } }
+} from 'virtual:karaoke-cms/config';
+```
+
+Add to your `src/env.d.ts` to get TypeScript types:
+
+```ts
+/// <reference types="@karaoke-cms/astro/client" />
+```
+
+### Collections
+
+`makeCollections()` creates Astro content collections from the vault:
+
+```ts
+// src/content.config.ts
+import { makeCollections } from '@karaoke-cms/astro/collections';
+import { loadEnv } from '@karaoke-cms/astro/env';
+
+const { KARAOKE_VAULT } = loadEnv(new URL('..', import.meta.url));
+export const collections = makeCollections(import.meta.url, KARAOKE_VAULT);
+```
+
+Collections are glob-loaded from `{vault}/blog/`, `{vault}/docs/`, and `{vault}/karaoke-cms/`. Only files with `publish: true` are included in production builds.
+
+### Menus
+
+`resolveMenus(vaultDir)` reads `{vault}/karaoke-cms/config/menus.yaml` and returns `ResolvedMenus`. When the file is absent, defaults are generated: a `main` menu with Blog/Docs/Tags (each hidden when the collection is empty) and a `footer` menu with the RSS link.
+
+The `Menu.astro` and `MenuItems.astro` components render named menus with `when: collection:name` visibility guards evaluated at render time via `getCollection()`.
+
+### Layout regions
+
+The `Base.astro` layout renders four configurable regions (top, left, right, bottom) using `RegionRenderer.astro`. Each region's component list is set in `karaoke.config.ts`:
+
+```ts
+layout: {
+  regions: {
+    top: { components: ['header', 'main-menu'] },
+    bottom: { components: ['footer'] },
+  }
+}
+```
+
+Available region components: `'header'`, `'main-menu'`, `'search'`, `'recent-posts'`, `'footer'`.
+
+## How it changes the behavior of the system
+
+- Without this package there is no karaoke-cms site — it is the root of the dependency graph.
+- It is the only place where vault config (`.env`, `collections.yaml`, `menus.yaml`) is read and compiled into the virtual module. Everything else reads from that module at build time.
+- It controls which pages exist: core routes (RSS, handbook) are always present; all other routes come from the active theme.
+- Privacy enforcement flows through `makeCollections()`: the `publish: true` filter is applied at the collection level, so unpublished content is never passed to Astro's static generator.
+- Theme loading uses a native `import()` bypass to avoid Vite interception, which is why theme packages ship `.astro` source files instead of pre-compiled output.

package/client.d.ts

@@ -6,7 +6,7 @@
  */
 
 declare module 'virtual:karaoke-cms/config' {
-  import type { ResolvedModules, ResolvedLayout, ResolvedCollections } from '@karaoke-cms/astro';
+  import type { ResolvedModules, ResolvedLayout, ResolvedCollections, ResolvedMenus } from '@karaoke-cms/astro';
 
   /** Site title from karaoke.config.ts */
   export const siteTitle: string;
@@ -18,4 +18,6 @@ declare module 'virtual:karaoke-cms/config' {
   export const resolvedLayout: ResolvedLayout;
   /** Resolved collections with enabled/disabled status for current build mode */
   export const resolvedCollections: ResolvedCollections;
+  /** Resolved menus from menus.yaml (defaults to main + footer when absent) */
+  export const resolvedMenus: ResolvedMenus;
 }

package/package.json

@@ -1,22 +1,17 @@
 {
   "name": "@karaoke-cms/astro",
   "type": "module",
-  "version": "0.6.3",
-  "description": "Astro integration for karaoke-cms — ships all routes, themes, and modules",
+  "version": "0.9.0",
+  "description": "Core Astro integration for karaoke-cms — virtual config, wikilinks, handbook routes",
   "main": "./src/index.ts",
   "exports": {
     ".": "./src/index.ts",
     "./client": "./client.d.ts",
     "./collections": "./src/collections.ts",
     "./env": "./src/utils/load-env.ts",
-    "./pages/index.astro": "./src/pages/index.astro",
-    "./pages/blog/index.astro": "./src/pages/blog/index.astro",
-    "./pages/blog/[slug].astro": "./src/pages/blog/[slug].astro",
-    "./pages/docs/index.astro": "./src/pages/docs/index.astro",
-    "./pages/docs/[slug].astro": "./src/pages/docs/[slug].astro",
-    "./pages/tags/index.astro": "./src/pages/tags/index.astro",
-    "./pages/tags/[tag].astro": "./src/pages/tags/[tag].astro",
-    "./pages/404.astro": "./src/pages/404.astro",
+    "./layouts/Base.astro": "./src/layouts/Base.astro",
+    "./consts": "./src/consts.ts",
+    "./components/ModuleLoader.astro": "./src/components/ModuleLoader.astro",
     "./pages/rss.xml.ts": "./src/pages/rss.xml.ts",
     "./pages/karaoke-cms/index.astro": "./src/pages/karaoke-cms/index.astro",
     "./pages/karaoke-cms/[...slug].astro": "./src/pages/karaoke-cms/[...slug].astro"
@@ -38,13 +33,14 @@
     "@astrojs/rss": "^4.0.17",
     "@astrojs/sitemap": "^3.7.1",
     "remark-wiki-link": "^2.0.1",
-    "yaml": "^2.7.0"
+    "yaml": "^2.7.0",
+    "zod": "^4.0.0"
   },
   "devDependencies": {
     "vitest": "^4.1.1",
     "astro": "^6.0.8"
   },
   "scripts": {
-    "test": "vitest run test/validate-config.test.js test/resolve-modules.test.js test/resolve-layout.test.js test/resolve-collections.test.js test/load-env.test.js"
+    "test": "vitest run test/validate-config.test.js test/theme-loading.test.js test/resolve-modules.test.js test/resolve-layout.test.js test/resolve-collections.test.js test/collections.test.js test/load-env.test.js test/resolve-menus.test.js"
   }
 }

package/src/blog-schema.ts

@@ -0,0 +1,13 @@
+import { z } from 'zod';
+
+/**
+ * Optional frontmatter schema extension for blog-theme-compatible posts.
+ * Pass as `opts.blogSchema` to `makeCollections()` when using @karaoke-cms/theme-blog.
+ *
+ * All fields are optional — posts without them validate fine against the base schema.
+ */
+export const blogThemeExtension = z.object({
+  cover_image: z.string().optional(),
+  featured:    z.boolean().optional().default(false),
+  abstract:    z.string().optional(),
+});

package/src/collections.ts

@@ -4,6 +4,7 @@ import { fileURLToPath } from 'url';
 import { join, resolve, isAbsolute } from 'path';
 import { resolveCollections } from './utils/resolve-collections.js';
 import type { CollectionConfig } from './types.js';
+export { blogThemeExtension } from './blog-schema.js';
 
 const baseSchema = z.object({
   title: z.string(),
@@ -29,6 +30,13 @@ const relaxedSchema = z.object({
   related: z.array(z.string()).optional(),
 });
 
+export interface MakeCollectionsOptions {
+  /** Per-collection overrides from karaoke.config.ts. */
+  collections?: Record<string, CollectionConfig>;
+  /** Zod schema extension merged into the blog collection schema. Use with @karaoke-cms/theme-blog. */
+  blogSchema?: z.ZodObject<z.ZodRawShape>;
+}
+
 /**
  * Create Astro content collections for karaoke-cms.
  *
@@ -41,7 +49,7 @@ const relaxedSchema = z.object({
  * @param vault - Path to the Obsidian vault root (where content/ lives).
  *   Absolute, or relative to `root`. Defaults to `root` when omitted (vault = project).
  *   Typically sourced from `loadEnv(new URL('..', import.meta.url)).KARAOKE_VAULT`.
- * @param configCollections - Optional per-collection overrides from karaoke.config.ts.
+ * @param opts - Optional config: collection overrides and blog schema extension.
  *
  * @example
  * // src/content.config.ts
@@ -49,25 +57,32 @@ const relaxedSchema = z.object({
  * import { loadEnv } from '@karaoke-cms/astro/env';
  * const env = loadEnv(new URL('..', import.meta.url));
  * export const collections = makeCollections(new URL('..', import.meta.url), env.KARAOKE_VAULT);
+ *
+ * @example With blog theme schema extension:
+ * import { makeCollections, blogThemeExtension } from '@karaoke-cms/astro/collections';
+ * export const collections = makeCollections(root, vault, { blogSchema: blogThemeExtension });
  */
 export function makeCollections(
   root: URL,
   vault?: string,
-  configCollections?: Record<string, CollectionConfig>,
+  opts?: MakeCollectionsOptions,
 ) {
   const rootDir = fileURLToPath(root);
   const vaultDir = vault
     ? (isAbsolute(vault) ? vault : resolve(rootDir, vault))
     : rootDir;
   const isProd = import.meta.env.PROD;
-  const resolved = resolveCollections(vaultDir, isProd, configCollections);
+  const resolved = resolveCollections(vaultDir, isProd, opts?.collections);
 
   const collections: Record<string, ReturnType<typeof defineCollection>> = {};
 
   if (resolved.blog?.enabled) {
+    const blogExt = opts?.blogSchema
+      ? baseSchema.merge(opts.blogSchema).extend({ comments: z.boolean().optional().default(true) })
+      : baseSchema.extend({ comments: z.boolean().optional().default(true) });
     collections.blog = defineCollection({
       loader: glob({ pattern: '**/*.md', base: join(vaultDir, 'blog') }),
-      schema: baseSchema.extend({ comments: z.boolean().optional().default(true) }),
+      schema: blogExt,
     });
   }
 

package/src/components/Menu.astro

@@ -0,0 +1,71 @@
+---
+import { resolvedCollections, resolvedMenus } from 'virtual:karaoke-cms/config';
+import { getCollection } from 'astro:content';
+import MenuItems from './MenuItems.astro';
+import type { ResolvedMenuEntry } from '../types.js';
+
+interface Props {
+  name: string;
+  class?: string;
+}
+
+const { name, class: className } = Astro.props;
+const pathname = Astro.url.pathname;
+const menu = resolvedMenus[name];
+if (!menu) return;
+
+// Evaluate `when: collection:name` visibility at render time.
+// getCollection() is Astro's per-build cached function — no extra filesystem reads.
+const collectionEmpty: Record<string, boolean> = {};
+
+async function isVisible(entry: ResolvedMenuEntry): Promise<boolean> {
+  if (!entry.when) return true;
+  if (!entry.when.startsWith('collection:')) {
+    if (import.meta.env.DEV) {
+      console.warn(
+        `[karaoke-cms] Unknown when: condition "${entry.when}" on menu entry "${entry.text}". ` +
+        `Only "collection:name" is supported in v1. Entry will always show.`,
+      );
+    }
+    return true;
+  }
+  const colName = entry.when.slice('collection:'.length);
+  if (!resolvedCollections[colName]?.enabled) return false;
+  if (!(colName in collectionEmpty)) {
+    try {
+      // colName is a runtime string from YAML, not a literal type.
+      // resolvedCollections[colName]?.enabled check above ensures it's a known collection.
+      // getCollection() throws if the collection is unknown — caught below.
+      const entries = await getCollection(colName as any, ({ data }: any) => data.publish === true);
+      collectionEmpty[colName] = entries.length === 0;
+    } catch {
+      collectionEmpty[colName] = true;
+    }
+  }
+  return !collectionEmpty[colName];
+}
+
+// Apply when: guards recursively so nested submenu entries also respect visibility.
+async function filterVisible(entries: ResolvedMenuEntry[]): Promise<ResolvedMenuEntry[]> {
+  const results = await Promise.all(
+    entries.map(async e => {
+      if (!(await isVisible(e))) return null;
+      const visibleChildren = await filterVisible(e.entries);
+      return { ...e, entries: visibleChildren };
+    })
+  );
+  return results.filter((e): e is ResolvedMenuEntry => e !== null);
+}
+
+const visibleEntries = await filterVisible(menu.entries);
+---
+
+{visibleEntries.length > 0 && (
+  <nav
+    class:list={['karaoke-menu', className]}
+    data-orientation={menu.orientation}
+    aria-label={name}
+  >
+    <MenuItems entries={visibleEntries} pathname={pathname} />
+  </nav>
+)}

package/src/components/MenuItems.astro

@@ -0,0 +1,28 @@
+---
+import type { ResolvedMenuEntry } from '../types.js';
+
+interface Props {
+  entries: ResolvedMenuEntry[];
+  pathname: string;
+}
+
+const { entries, pathname } = Astro.props;
+---
+
+<ul>
+  {entries.map(entry => (
+    <li class:list={{ 'has-submenu': entry.entries.length > 0 }}>
+      {entry.href ? (
+        <a
+          href={entry.href}
+          aria-current={pathname === entry.href || pathname.startsWith(entry.href + '/') ? 'page' : undefined}
+        >{entry.text}</a>
+      ) : (
+        <span>{entry.text}</span>
+      )}
+      {entry.entries.length > 0 && (
+        <Astro.self entries={entry.entries} pathname={pathname} />
+      )}
+    </li>
+  ))}
+</ul>

package/src/components/regions/MainMenu.astro

@@ -1,22 +1,4 @@
 ---
-const pathname = Astro.url.pathname;
+import Menu from '../Menu.astro';
 ---
-<nav>
-  <ul>
-    <li>
-      <a href="/blog" aria-current={pathname.startsWith('/blog') ? 'page' : undefined}>
-        Blog
-      </a>
-    </li>
-    <li>
-      <a href="/docs" aria-current={pathname.startsWith('/docs') ? 'page' : undefined}>
-        Docs
-      </a>
-    </li>
-    <li>
-      <a href="/tags" aria-current={pathname.startsWith('/tags') ? 'page' : undefined}>
-        Tags
-      </a>
-    </li>
-  </ul>
-</nav>
+<Menu name="main" />

package/src/components/regions/SiteFooter.astro

@@ -1,7 +1,7 @@
 ---
+import Menu from '../Menu.astro';
 ---
-<div>
-  <a href="/rss.xml">RSS</a> · Built with
-  <a href="https://obsidian.md" rel="noopener">Obsidian</a> +
-  <a href="https://astro.build" rel="noopener">Astro</a>
+<Menu name="footer" />
+<div class="footer-attr">
+  Built with <a href="https://karaoke-cms.org">karaoke-cms</a>
 </div>

package/src/index.ts

@@ -1,24 +1,40 @@
 import type { AstroIntegration } from 'astro';
-import { fileURLToPath } from 'url';
-import { join, resolve, isAbsolute } from 'path';
+import { fileURLToPath, pathToFileURL } from 'url';
+import { resolve, isAbsolute } from 'path';
+import { createRequire } from 'module';
 import { wikiLinkPlugin } from 'remark-wiki-link';
 import sitemap from '@astrojs/sitemap';
-import { getTheme, validateModules } from './validate-config.js';
+import { validateModules } from './validate-config.js';
 import { resolveModules } from './utils/resolve-modules.js';
 import { resolveLayout } from './utils/resolve-layout.js';
 import { resolveCollections } from './utils/resolve-collections.js';
-import type { KaraokeConfig, ResolvedModules, ResolvedLayout, ResolvedCollections } from './types.js';
+import { resolveMenus } from './utils/resolve-menus.js';
+import type { KaraokeConfig, ResolvedModules, ResolvedLayout, ResolvedCollections, ResolvedMenus } from './types.js';
 
-const __dirname = fileURLToPath(new URL('.', import.meta.url));
+/**
+ * Resolve a theme config value to an npm package name.
+ * Bare strings ('default', 'minimal') map to @karaoke-cms/theme-* with a deprecation warning.
+ */
+function resolveThemePkg(theme: string | undefined): string {
+  const raw = theme ?? '@karaoke-cms/theme-default';
+  if (raw === 'default' || raw === 'minimal') {
+    console.warn(
+      `[karaoke-cms] theme: '${raw}' is deprecated. Use theme: '@karaoke-cms/theme-${raw}' instead.`,
+    );
+    return `@karaoke-cms/theme-${raw}`;
+  }
+  return raw;
+}
 
 /**
  * karaoke() — the main Astro integration for karaoke-cms.
  *
- * Injects all routes (/, /blog, /blog/[slug], /docs, /docs/[slug],
- * /tags, /tags/[tag], /rss.xml, /404), sets up the @theme CSS alias,
- * enables wikilinks, and provides a virtual module with your resolved config.
+ * Loads the active theme package (an Astro integration) and registers it
+ * as a nested integration. The theme owns all content routes (/, /blog, /docs,
+ * etc.), the @theme CSS alias, and its own 404 page.
  *
- * The /karaoke-cms and /karaoke-cms/[...slug] routes are injected in dev only.
+ * Core always registers: /rss.xml, /karaoke-cms/[...slug] (dev only), wikilinks,
+ * sitemap, and the virtual:karaoke-cms/config module.
  *
  * @example
  * // astro.config.mjs
@@ -30,63 +46,66 @@ const __dirname = fileURLToPath(new URL('.', import.meta.url));
  *   site: 'https://your-site.pages.dev',
  *   integrations: [karaoke(karaokeConfig)],
  * });
- *
- * Module slots (contract for Base.astro — extensible in v0.7+):
- *   'nav'         — rendered in the nav bar (e.g., Search)
- *   'post-footer' — rendered after post content (e.g., Comments)
  */
 export default function karaoke(config: KaraokeConfig = {}): AstroIntegration {
-  const themesDir = join(__dirname, 'themes');
-  const theme = getTheme(config, themesDir);
   validateModules(config);
   const resolved = resolveModules(config);
   const layout = resolveLayout(config);
 
+  let _resolvedCollections: ResolvedCollections | undefined;
+
   return {
     name: '@karaoke-cms/astro',
     hooks: {
-      'astro:config:setup'({ injectRoute, updateConfig, command, config: astroConfig }) {
+      async 'astro:config:setup'({ injectRoute, updateConfig, command, config: astroConfig }) {
         const rootDir = fileURLToPath(astroConfig.root);
         const vaultDir = config.vault
           ? (isAbsolute(config.vault) ? config.vault : resolve(rootDir, config.vault))
           : rootDir;
         const isProd = command === 'build';
-        const resolvedCollections = resolveCollections(vaultDir, isProd, config.collections);
+        _resolvedCollections = resolveCollections(vaultDir, isProd, config.collections);
+        const _resolvedMenus = resolveMenus(vaultDir);
 
-        // ── Inject all framework routes ──────────────────────────────────
-        injectRoute({ pattern: '/', entrypoint: '@karaoke-cms/astro/pages/index.astro' });
-        injectRoute({ pattern: '/blog', entrypoint: '@karaoke-cms/astro/pages/blog/index.astro' });
-        injectRoute({ pattern: '/blog/[slug]', entrypoint: '@karaoke-cms/astro/pages/blog/[slug].astro' });
-        injectRoute({ pattern: '/docs', entrypoint: '@karaoke-cms/astro/pages/docs/index.astro' });
-        injectRoute({ pattern: '/docs/[slug]', entrypoint: '@karaoke-cms/astro/pages/docs/[slug].astro' });
-        injectRoute({ pattern: '/tags', entrypoint: '@karaoke-cms/astro/pages/tags/index.astro' });
-        injectRoute({ pattern: '/tags/[tag]', entrypoint: '@karaoke-cms/astro/pages/tags/[tag].astro' });
-        injectRoute({ pattern: '/404', entrypoint: '@karaoke-cms/astro/pages/404.astro' });
+        // ── Load active theme as a nested Astro integration ───────────────
+        // Resolve the theme package from the user's project root, not from
+        // this package's location, so the user's node_modules is searched.
+        const themePkg = resolveThemePkg(config.theme);
+        const projectRequire = createRequire(new URL('package.json', astroConfig.root));
+        let resolvedThemePath: string;
+        try {
+          resolvedThemePath = projectRequire.resolve(themePkg);
+        } catch {
+          throw new Error(
+            `[karaoke-cms] Theme package "${themePkg}" is not installed.\n` +
+            `Run: pnpm add ${themePkg}`,
+          );
+        }
+        // Use new Function to bypass Vite's import() interception —
+        // this runs the native Node.js ESM loader, not Vite's module runner.
+        const nativeImport: (specifier: string) => Promise<unknown> =
+          new Function('specifier', 'return import(specifier)');
+        const themeModule = await nativeImport(pathToFileURL(resolvedThemePath).href) as {
+          default: (cfg: KaraokeConfig) => AstroIntegration;
+        };
+        const themeIntegration = themeModule.default(config);
+
+        // ── Core routes — always present regardless of theme ─────────────
         injectRoute({ pattern: '/rss.xml', entrypoint: '@karaoke-cms/astro/pages/rss.xml.ts' });
 
-        // ── Handbook routes — dev only ───────────────────────────────────
-        if (resolvedCollections['karaoke-cms']?.enabled) {
+        // Handbook routes — dev only
+        if (_resolvedCollections['karaoke-cms']?.enabled) {
           injectRoute({ pattern: '/karaoke-cms', entrypoint: '@karaoke-cms/astro/pages/karaoke-cms/index.astro' });
           injectRoute({ pattern: '/karaoke-cms/[...slug]', entrypoint: '@karaoke-cms/astro/pages/karaoke-cms/[...slug].astro' });
         }
 
         updateConfig({
-          integrations: [sitemap()],
+          integrations: [sitemap(), themeIntegration],
           vite: {
-            resolve: {
-              alias: {
-                // @theme → packages/astro/src/themes/<active-theme>/
-                '@theme': join(themesDir, theme),
-              },
-            },
-            plugins: [virtualConfigPlugin(config, resolved, layout, resolvedCollections)],
+            plugins: [virtualConfigPlugin(config, resolved, layout, _resolvedCollections, _resolvedMenus)],
           },
           markdown: {
             remarkPlugins: [
               [wikiLinkPlugin, {
-                // [[blog/hello-world]] → /blog/hello-world/
-                // [[docs/getting-started]] → /docs/getting-started/
-                // [[blog/hello-world|Hello World]] → link text "Hello World"
                 pageResolver: (name: string) => [name.toLowerCase().replace(/ /g, '-')],
                 hrefTemplate: (permalink: string) => `/${permalink}/`,
                 aliasDivider: '|',
@@ -95,6 +114,19 @@ export default function karaoke(config: KaraokeConfig = {}): AstroIntegration {
           },
         });
       },
+
+      'astro:build:done'({ pages }) {
+        if (!_resolvedCollections?.docs?.enabled) return;
+        // pages is { pathname: string }[] — check if any /docs page was rendered
+        const hasDocsRoute = (pages ?? []).some(p => p.pathname?.startsWith('docs'));
+        if (!hasDocsRoute) {
+          console.warn(
+            '[karaoke-cms] Your vault has a docs collection enabled but the active theme ' +
+            'has no /docs route. Published docs entries will not be accessible. ' +
+            'Consider using @karaoke-cms/theme-default which includes /docs routes.',
+          );
+        }
+      },
     },
   };
 }
@@ -108,6 +140,7 @@ function virtualConfigPlugin(
   resolved: ResolvedModules,
   layout: ResolvedLayout,
   resolvedCollections: ResolvedCollections,
+  resolvedMenus: ResolvedMenus,
 ) {
   const VIRTUAL_ID = 'virtual:karaoke-cms/config';
   const RESOLVED_ID = '\0' + VIRTUAL_ID;
@@ -125,10 +158,11 @@ export const siteDescription = ${JSON.stringify(config.description ?? '')};
 export const resolvedModules = ${JSON.stringify(resolved)};
 export const resolvedLayout = ${JSON.stringify(layout)};
 export const resolvedCollections = ${JSON.stringify(resolvedCollections)};
+export const resolvedMenus = ${JSON.stringify(resolvedMenus)};
 `;
       }
     },
   };
 }
 
-export type { KaraokeConfig, ResolvedModules, ResolvedLayout, ResolvedCollections, RegionComponent } from './types.js';
+export type { KaraokeConfig, ResolvedModules, ResolvedLayout, ResolvedCollections, RegionComponent, ResolvedMenus, ResolvedMenu, ResolvedMenuEntry } from './types.js';

package/src/layouts/Base.astro

@@ -1,8 +1,7 @@
 ---
 import '@theme/styles.css';
 import RegionRenderer from '../components/RegionRenderer.astro';
-import { resolvedModules, resolvedLayout } from 'virtual:karaoke-cms/config';
-import { SITE_TITLE } from '../consts';
+import { siteTitle, resolvedModules, resolvedLayout } from 'virtual:karaoke-cms/config';
 
 interface Props {
   title: string;
@@ -28,14 +27,14 @@ const hasRight = Astro.slots.has('right') || layout.regions.right.components.len
     <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
     <link rel="icon" href="/favicon.ico" />
     <meta name="generator" content={Astro.generator} />
-    <title>{title === SITE_TITLE ? title : `${title} — ${SITE_TITLE}`}</title>
+    <title>{title === siteTitle ? title : `${title} — ${siteTitle}`}</title>
     {description && <meta name="description" content={description} />}
     <meta property="og:title" content={title} />
     <meta property="og:type" content={type} />
     <meta property="og:url" content={canonicalUrl} />
     {description && <meta property="og:description" content={description} />}
     <meta name="twitter:card" content="summary" />
-    <link rel="alternate" type="application/rss+xml" title={SITE_TITLE} href="/rss.xml" />
+    <link rel="alternate" type="application/rss+xml" title={siteTitle} href="/rss.xml" />
   </head>
   <body>
     <header>
@@ -65,9 +64,11 @@ const hasRight = Astro.slots.has('right') || layout.regions.right.components.len
       )}
     </div>
     <footer>
-      <slot name="bottom">
-        <RegionRenderer components={layout.regions.bottom.components} {searchEnabled} />
-      </slot>
+      <div class="footer-inner">
+        <slot name="bottom">
+          <RegionRenderer components={layout.regions.bottom.components} {searchEnabled} />
+        </slot>
+      </div>
     </footer>
   </body>
 </html>

package/src/types.ts

@@ -73,3 +73,37 @@ export interface ResolvedLayout {
     bottom: { components: RegionComponent[] };
   };
 }
+
+// ── Menu types ─────────────────────────────────────────────────────────────────
+
+/** Raw shape of one entry in menus.yaml (used to type the parsed YAML). */
+export interface MenuEntryConfig {
+  text: string;
+  href?: string;
+  weight?: number;
+  /** Visibility condition — only 'collection:name' supported in v1. */
+  when?: string;
+  entries?: MenuEntryConfig[];
+}
+
+/** Raw shape of one menu block in menus.yaml. */
+export interface MenuConfig {
+  orientation?: 'horizontal' | 'vertical';
+  entries?: MenuEntryConfig[];
+}
+
+export interface ResolvedMenuEntry {
+  text: string;
+  href?: string;
+  weight: number;
+  when?: string;
+  entries: ResolvedMenuEntry[];
+}
+
+export interface ResolvedMenu {
+  name: string;
+  orientation: 'horizontal' | 'vertical';
+  entries: ResolvedMenuEntry[];
+}
+
+export type ResolvedMenus = Record<string, ResolvedMenu>;