@karaoke-cms/astro 0.9.3 → 0.9.5

package/README.md

@@ -1,10 +1,14 @@
 # @karaoke-cms/astro
 
-Core Astro integration for karaoke-cms. Every karaoke-cms project depends on this package.
+Core Astro integration for karaoke-cms. Wires up themes, modules, collections, menus, and the virtual config module at build time. Every karaoke-cms project depends on this package.
 
-## Where it belongs
+## Installation
 
-`packages/astro/` in the monorepo. Users install it as a dependency and register it in `astro.config.mjs`:
+```bash
+npm install @karaoke-cms/astro
+```
+
+## Usage
 
 ```js
 // astro.config.mjs
@@ -18,77 +22,102 @@ export default defineConfig({
 });
 ```
 
-## What it does
+```ts
+// karaoke.config.ts
+import { defineConfig } from '@karaoke-cms/astro';
+import { loadEnv } from '@karaoke-cms/astro/env';
+import { blog } from '@karaoke-cms/module-blog';
+import { docs } from '@karaoke-cms/module-docs';
+import { themeDefault } from '@karaoke-cms/theme-default';
 
-`karaoke(config)` is an Astro integration that wires up the full karaoke-cms runtime at build time:
+const env = loadEnv(new URL('.', import.meta.url));
 
-- **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`
+export default defineConfig({
+  vault: env.KARAOKE_VAULT,
+  title: 'My Site',
+  description: 'What this site is about.',
+  theme: themeDefault({
+    implements: [blog({ mount: '/blog' }), docs({ mount: '/docs' })],
+  }),
+});
+```
 
-### Virtual module
+## Configuration
 
-Every page and component in the framework reads config from `virtual:karaoke-cms/config`:
+All fields are optional. Defaults produce a working site with no content.
 
-```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';
-```
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `vault` | `string` | project root | Path to the Obsidian vault directory (absolute or relative) |
+| `title` | `string` | `'Karaoke'` | Site title for browser tab and nav |
+| `description` | `string` | `''` | Site description for RSS and OG tags |
+| `theme` | `ThemeInstance` | — | Theme from `themeDefault()` or similar |
+| `modules` | `ModuleInstance[]` | `[]` | Additional modules not covered by the theme |
+| `comments` | `CommentsConfig` | — | Giscus comments config |
+| `collections` | `Record<string, CollectionConfig>` | — | Per-collection mode overrides |
+| `layout.regions` | `{ top, left, right, bottom }` | — | Region component lists |
 
-Add to your `src/env.d.ts` to get TypeScript types:
+## Exports
 
-```ts
-/// <reference types="@karaoke-cms/astro/client" />
-```
+### `@karaoke-cms/astro` — main integration
 
-### Collections
+- `karaoke(config)` — Astro integration (default export)
+- `defineConfig(config)` — identity wrapper for type inference
+- `defineModule(def)` — create a module factory
+- `defineTheme(def)` — create a theme factory
 
-`makeCollections()` creates Astro content collections from the vault:
+### `@karaoke-cms/astro/env`
 
-```ts
-// src/content.config.ts
-import { makeCollections } from '@karaoke-cms/astro/collections';
-import { loadEnv } from '@karaoke-cms/astro/env';
+- `loadEnv(dir)` — reads `.env.default` and `.env` from `dir`, returns merged record
+
+### `@karaoke-cms/astro/collections`
+
+- `makeCollections(root, vault?, collections?)` — creates Astro content collections from the vault
+
+### `virtual:karaoke-cms/config`
+
+Available in any page or component at build time:
 
-const { KARAOKE_VAULT } = loadEnv(new URL('..', import.meta.url));
-export const collections = makeCollections(import.meta.url, KARAOKE_VAULT);
+```ts
+import {
+  siteTitle,           // string
+  siteDescription,     // string
+  resolvedCollections, // Record<string, { modes, label, enabled }>
+  resolvedMenus,       // Record<string, { name, orientation, entries }>
+  resolvedLayout,      // { regions: { top, left, right, bottom } }
+  resolvedModules,     // { comments: { enabled, repo, repoId, category, categoryId } }
+  blogMount,           // string — the blog module's mount path
+} from 'virtual:karaoke-cms/config';
 ```
 
-Collections are glob-loaded from `{vault}/blog/`, `{vault}/docs/`, and `{vault}/karaoke-cms/`. Only files with `publish: true` are included in production builds.
+Add to `src/env.d.ts` for TypeScript types:
 
-### Menus
+```ts
+/// <reference types="@karaoke-cms/astro/client" />
+```
 
-`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.
+## Menus
 
-The `Menu.astro` and `MenuItems.astro` components render named menus with `when: collection:name` visibility guards evaluated at render time via `getCollection()`.
+Define menus in `{vault}/karaoke-cms/config/menus.yaml`. When absent, defaults are generated: a `main` menu with Blog/Docs/Tags and a `footer` menu with the RSS link. Entries support `when: collection:name` to hide automatically when a collection is empty.
 
-### Layout regions
+## 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`:
+Four regions (top, left, right, bottom) accept component lists from `karaoke.config.ts`:
 
 ```ts
 layout: {
   regions: {
-    top: { components: ['header', 'main-menu'] },
+    top:    { components: ['header', 'main-menu'] },
+    right:  { components: ['recent-posts'] },
     bottom: { components: ['footer'] },
   }
 }
 ```
 
-Available region components: `'header'`, `'main-menu'`, `'search'`, `'recent-posts'`, `'footer'`.
+Available components: `'header'`, `'main-menu'`, `'search'`, `'recent-posts'`, `'footer'`.
 
-## How it changes the behavior of the system
+## What's new in 0.9.5
 
-- 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.
+- **`isThemeInstance` type-guard** added — fixes a runtime crash in the `astro:config:setup` hook when a `ThemeInstance` was passed
+- **Module array API** — `modules` in config is now `ModuleInstance[]` (was a legacy object shape in some docs)
+- **Tighter `astro.config.mjs` error handling** — missing `karaoke.config.ts` is now distinguished from missing dependencies of that file; the latter now surfaces the real error instead of silently falling back to empty config

package/client.d.ts

@@ -20,4 +20,6 @@ declare module 'virtual:karaoke-cms/config' {
   export const resolvedCollections: ResolvedCollections;
   /** Resolved menus from menus.yaml (defaults to main + footer when absent) */
   export const resolvedMenus: ResolvedMenus;
+  /** Mount path of the blog module (e.g. '/blog' or '/news'). Defaults to '/blog'. */
+  export const blogMount: string;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@karaoke-cms/astro",
   "type": "module",
-  "version": "0.9.3",
+  "version": "0.9.5",
   "description": "Core Astro integration for karaoke-cms — virtual config, wikilinks, handbook routes",
   "main": "./src/index.ts",
   "exports": {
@@ -43,6 +43,6 @@
     "astro": "^6.0.8"
   },
   "scripts": {
-    "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 test/define-module.test.js test/define-theme.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 test/define-module.test.js test/define-theme.test.js test/theme-default-styles.test.js test/module-injection.test.js"
   }
 }

package/src/collections.ts

@@ -16,6 +16,7 @@ const baseSchema = z.object({
   description: z.string().optional(),
   reading_time: z.number().optional(),
   related: z.array(z.string()).optional(),
+  featured_image: z.string().optional(),
 });
 
 // Relaxed schema for handbook / custom collections — title is optional
@@ -89,7 +90,10 @@ export function makeCollections(
   if (resolved.docs?.enabled) {
     collections.docs = defineCollection({
       loader: glob({ pattern: '**/*.md', base: join(vaultDir, 'docs') }),
-      schema: baseSchema.extend({ comments: z.boolean().optional().default(false) }),
+      schema: baseSchema.extend({
+        featured_image: z.string().optional(),
+        comments: z.boolean().optional().default(false),
+      }),
     });
   }
 

package/src/components/RegionRenderer.astro

@@ -11,10 +11,10 @@ import type { RegionComponent } from '../types.js';
 
 interface Props {
   components: RegionComponent[];
-  searchEnabled: boolean;
+  searchEnabled?: boolean;
 }
 
-const { components, searchEnabled } = Astro.props;
+const { components, searchEnabled = false } = Astro.props;
 ---
 
 {components.includes('header')       && <SiteHeader />}

package/src/define-module.ts

@@ -3,10 +3,16 @@ import type { ModuleInstance, ModuleMenuEntry } from './types.js';
 export interface ModuleDefinition {
   id: string;
   cssContract: readonly string[];
-  defaultCss?: () => Promise<unknown>;
+  /** Absolute path to a default CSS file. On first dev run, copied to src/styles/{id}.css. */
+  defaultCssPath?: string;
   routes: (mount: string) => Array<{ pattern: string; entrypoint: string }>;
   menuEntries: (mount: string, id: string) => ModuleMenuEntry[];
   collection?: () => unknown;
+  /**
+   * Pages to scaffold into the user's src/pages/ on first dev run.
+   * src: absolute path inside the npm package. dest: relative to src/pages/.
+   */
+  scaffoldPages?: (mount: string) => Array<{ src: string; dest: string }>;
 }
 
 /**
@@ -22,17 +28,21 @@ export interface ModuleDefinition {
  * modules: [blog({ mount: '/blog' })]
  */
 export function defineModule(def: ModuleDefinition) {
-  return function moduleFactory(config: { id?: string; mount: string }): ModuleInstance {
+  return function moduleFactory(config: { id?: string; mount: string; enabled?: boolean }): ModuleInstance {
     const id = config.id ?? def.id;
     const mount = config.mount.replace(/\/$/, '');
+    const enabled = config.enabled ?? true;
     return {
       _type: 'module-instance',
       id,
       mount,
+      enabled,
       routes: def.routes(mount),
       menuEntries: def.menuEntries(mount, id),
       cssContract: def.cssContract,
-      hasDefaultCss: !!def.defaultCss,
+      hasDefaultCss: !!def.defaultCssPath,
+      scaffoldPages: def.scaffoldPages?.(mount),
+      defaultCssPath: def.defaultCssPath,
     };
   };
 }

package/src/define-theme.ts

@@ -1,37 +1,34 @@
 import type { AstroIntegration } from 'astro';
 import type { ModuleInstance, ThemeInstance } from './types.js';
 
-export interface ThemeFactoryConfig {
-  implements?: ModuleInstance[];
-}
+export interface ThemeFactoryConfig {}
 
 export interface ThemeDefinition {
   id: string;
-  toAstroIntegration: (config: ThemeFactoryConfig) => AstroIntegration;
+  toAstroIntegration: (config: ThemeFactoryConfig, modules: ModuleInstance[]) => AstroIntegration;
 }
 
 /**
  * Define a karaoke-cms theme.
  *
- * Returns a factory function. Call the factory with `{ implements: [...] }` to
- * declare which module instances this theme provides CSS for. The result is a
- * ThemeInstance that can be passed to `defineConfig({ theme: ... })`.
+ * Returns a factory function. Call the factory (optionally with config) to get a
+ * ThemeInstance that can be passed to `defineConfig({ theme: ... })`. Modules are
+ * passed by the karaoke() integration at build time via `toAstroIntegration(modules)`.
  *
  * @example
  * export const themeDefault = defineTheme({
  *   id: 'theme-default',
- *   toAstroIntegration: (config) => ({ name: '...', hooks: { ... } }),
+ *   toAstroIntegration: (config, modules) => ({ name: '...', hooks: { ... } }),
  * })
  * // In karaoke.config.ts:
- * theme: themeDefault({ implements: [blog({ mount: '/blog' })] })
+ * theme: themeDefault()
  */
 export function defineTheme(def: ThemeDefinition) {
   return function themeFactory(config: ThemeFactoryConfig = {}): ThemeInstance {
     return {
       _type: 'theme-instance',
       id: def.id,
-      implementedModuleIds: (config.implements ?? []).map(m => m.id),
-      toAstroIntegration: () => def.toAstroIntegration(config),
+      toAstroIntegration: (modules: ModuleInstance[]) => def.toAstroIntegration(config, modules),
     };
   };
 }

package/src/index.ts

@@ -1,7 +1,7 @@
 import type { AstroIntegration } from 'astro';
-import { fileURLToPath, pathToFileURL } from 'url';
-import { resolve, isAbsolute } from 'path';
-import { createRequire } from 'module';
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { resolve, isAbsolute, dirname } from 'path';
 import { wikiLinkPlugin } from 'remark-wiki-link';
 import sitemap from '@astrojs/sitemap';
 import { validateModules } from './validate-config.js';
@@ -9,34 +9,15 @@ import { resolveModules } from './utils/resolve-modules.js';
 import { resolveLayout } from './utils/resolve-layout.js';
 import { resolveCollections } from './utils/resolve-collections.js';
 import { resolveMenus } from './utils/resolve-menus.js';
-import type { KaraokeConfig, ResolvedModules, ResolvedLayout, ResolvedCollections, ResolvedMenus, ThemeInstance } from './types.js';
-
-function isThemeInstance(theme: unknown): theme is ThemeInstance {
-  return typeof theme === 'object' && theme !== null &&
-    (theme as ThemeInstance)._type === 'theme-instance';
-}
-
-/**
- * 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;
-}
+import type { KaraokeConfig, ResolvedModules, ResolvedLayout, ResolvedCollections, ResolvedMenus } from './types.js';
 
 /**
  * karaoke() — the main Astro integration for karaoke-cms.
  *
- * 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.
+ * Loads the active theme (a ThemeInstance from defineTheme()) and registers it
+ * as a nested integration. The theme owns content routes (/, /docs, /tags, etc.)
+ * and the @theme CSS alias. Modules declared in config.modules[] have their
+ * routes injected by this integration.
  *
  * Core always registers: /rss.xml, /karaoke-cms/[...slug] (dev only), wikilinks,
  * sitemap, and the virtual:karaoke-cms/config module.
@@ -57,11 +38,23 @@ export function defineConfig(config: KaraokeConfig): KaraokeConfig {
   return config;
 }
 
+function isThemeInstance(theme: unknown): theme is ThemeInstance {
+  return typeof theme === 'object' && theme !== null && (theme as ThemeInstance)._type === 'theme-instance';
+}
+
 export default function karaoke(config: KaraokeConfig = {}): AstroIntegration {
   validateModules(config);
   const resolved = resolveModules(config);
   const layout = resolveLayout(config);
 
+  if (!config.theme) {
+    throw new Error(
+      '[karaoke-cms] No theme configured. Add theme: themeDefault() to your karaoke.config.ts.\n' +
+      'Install: pnpm add @karaoke-cms/theme-default',
+    );
+  }
+
+  const theme = config.theme;
   let _resolvedCollections: ResolvedCollections | undefined;
 
   return {
@@ -74,36 +67,64 @@ export default function karaoke(config: KaraokeConfig = {}): AstroIntegration {
           : rootDir;
         const isProd = command === 'build';
         _resolvedCollections = resolveCollections(vaultDir, isProd, config.collections);
-        const _resolvedMenus = resolveMenus(vaultDir);
+        const modules = (config.modules ?? []).filter(m => m.enabled !== false);
+        const _resolvedMenus = resolveMenus(vaultDir, modules);
+
+        // ── Scaffold module pages and CSS on first dev run ────────────────
+        if (command === 'dev') {
+          for (const mod of modules) {
+            if (mod.scaffoldPages) {
+              for (const { src, dest } of mod.scaffoldPages) {
+                if (!existsSync(src)) continue;
+                const destAbs = resolve(rootDir, 'src/pages', dest);
+                if (!existsSync(destAbs)) {
+                  mkdirSync(dirname(destAbs), { recursive: true });
+                  copyFileSync(src, destAbs);
+                  console.log(`[karaoke-cms] Scaffolded src/pages/${dest}`);
+                }
+              }
+            }
+            if (mod.defaultCssPath && existsSync(mod.defaultCssPath)) {
+              const stylesDir = resolve(rootDir, 'src/styles');
+              const cssDest = resolve(stylesDir, `${mod.id}.css`);
+              if (!existsSync(cssDest)) {
+                mkdirSync(stylesDir, { recursive: true });
+                copyFileSync(mod.defaultCssPath, cssDest);
+                console.log(`[karaoke-cms] Scaffolded src/styles/${mod.id}.css`);
+              }
+              const globalCss = resolve(stylesDir, 'global.css');
+              const importLine = `@import './${mod.id}.css';`;
+              if (existsSync(globalCss)) {
+                const content = readFileSync(globalCss, 'utf8');
+                if (!content.includes(importLine)) {
+                  writeFileSync(globalCss, importLine + '\n' + content);
+                  console.log(`[karaoke-cms] Added @import '${mod.id}.css' to global.css`);
+                }
+              } else {
+                mkdirSync(stylesDir, { recursive: true });
+                writeFileSync(globalCss, importLine + '\n');
+                console.log(`[karaoke-cms] Created src/styles/global.css with @import '${mod.id}.css'`);
+              }
+            }
+          }
+        }
+
+        // ── Load theme and inject module routes ───────────────────────────
+        const themeIntegration = theme.toAstroIntegration(modules);
 
-        // ── Load active theme as a nested Astro integration ───────────────
-        let themeIntegration: AstroIntegration;
+        for (const mod of modules) {
+          for (const route of mod.routes) {
+            injectRoute(route);
+          }
+        }
 
+        // ── Module routes — injected from implements[] on the ThemeInstance ──
         if (isThemeInstance(config.theme)) {
-          // New API: theme is a ThemeInstance from defineTheme()
-          themeIntegration = config.theme.toAstroIntegration();
-        } else {
-          // Legacy API: theme is a package name string.
-          // Resolve from the user's project root so their node_modules is searched.
-          const themePkg = resolveThemePkg(config.theme as string | undefined);
-          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}`,
-            );
+          for (const mod of config.theme.implementedModules ?? []) {
+            for (const route of mod.routes) {
+              injectRoute({ pattern: route.pattern, entrypoint: route.entrypoint });
+            }
           }
-          // 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;
-          };
-          themeIntegration = themeModule.default(config);
         }
 
         // ── Core routes — always present regardless of theme ─────────────
@@ -176,6 +197,9 @@ 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 const blogMount = ${JSON.stringify(
+  (config.modules ?? []).find((m: { id: string; mount: string }) => m.id === 'blog')?.mount ?? '/blog'
+)};
 `;
       }
     },

package/src/layouts/DefaultPage.astro

@@ -2,7 +2,7 @@
 import '@theme/styles.css';
 import Base from './Base.astro';
 import RegionRenderer from '../components/RegionRenderer.astro';
-import { resolvedModules, resolvedLayout } from 'virtual:karaoke-cms/config';
+import { resolvedLayout } from 'virtual:karaoke-cms/config';
 
 interface Props {
   title:        string;
@@ -13,9 +13,7 @@ interface Props {
 }
 
 const { title, description, type = 'website', variant = 'default' } = Astro.props;
-const layout        = resolvedLayout;
-const modules       = resolvedModules;
-const searchEnabled = modules.search.enabled;
+const layout = resolvedLayout;
 
 const isLanding = variant === 'landing';
 
@@ -25,10 +23,10 @@ const hasRight = !isLanding && (Astro.slots.has('right') || layout.regions.right
 ---
 
 <Base {title} {description} {type}>
-  <header>
+  <header class:list={{ 'landing-header': isLanding }}>
     <div class="header-inner">
       <slot name="top">
-        <RegionRenderer components={layout.regions.top.components} {searchEnabled} />
+        <RegionRenderer components={layout.regions.top.components} searchEnabled={false} />
       </slot>
       <slot name="header-cta" />
     </div>
@@ -49,7 +47,7 @@ const hasRight = !isLanding && (Astro.slots.has('right') || layout.regions.right
       {hasLeft && (
         <aside class="region-left">
           <slot name="left">
-            <RegionRenderer components={layout.regions.left.components} {searchEnabled} />
+            <RegionRenderer components={layout.regions.left.components} searchEnabled={false} />
           </slot>
         </aside>
       )}
@@ -59,7 +57,7 @@ const hasRight = !isLanding && (Astro.slots.has('right') || layout.regions.right
       {hasRight && (
         <aside class="region-right">
           <slot name="right">
-            <RegionRenderer components={layout.regions.right.components} {searchEnabled} />
+            <RegionRenderer components={layout.regions.right.components} searchEnabled={false} />
           </slot>
         </aside>
       )}
@@ -69,7 +67,7 @@ const hasRight = !isLanding && (Astro.slots.has('right') || layout.regions.right
   <footer>
     <div class="footer-inner">
       <slot name="bottom">
-        <RegionRenderer components={layout.regions.bottom.components} {searchEnabled} />
+        <RegionRenderer components={layout.regions.bottom.components} searchEnabled={false} />
       </slot>
     </div>
   </footer>

package/src/types.ts

@@ -15,6 +15,15 @@ export interface ResolvedCollection {
 
 export type ResolvedCollections = Record<string, ResolvedCollection>;
 
+export interface CommentsConfig {
+  enabled?: boolean;
+  /** GitHub repo in "owner/repo" format */
+  repo?: string;
+  repoId?: string;
+  category?: string;
+  categoryId?: string;
+}
+
 export interface KaraokeConfig {
   /**
    * Path to the Obsidian vault root (where content/ lives).
@@ -31,17 +40,10 @@ export interface KaraokeConfig {
   description?: string;
   /** Theme — package name string (legacy) or a ThemeInstance from defineTheme(). */
   theme?: string | ThemeInstance;
-  modules?: {
-    search?: { enabled?: boolean };
-    comments?: {
-      enabled?: boolean;
-      /** GitHub repo in "owner/repo" format */
-      repo?: string;
-      repoId?: string;
-      category?: string;
-      categoryId?: string;
-    };
-  };
+  /** Modules to activate. Each is a ModuleInstance from defineModule(). */
+  modules?: ModuleInstance[];
+  /** Giscus comments configuration. */
+  comments?: CommentsConfig;
   layout?: {
     regions?: {
       top?:    { components?: RegionComponent[] };
@@ -54,7 +56,6 @@ export interface KaraokeConfig {
 
 /** Resolved (defaults filled in) modules config — available at build time via virtual module. */
 export interface ResolvedModules {
-  search: { enabled: boolean };
   comments: {
     enabled: boolean;
     repo: string;
@@ -124,10 +125,24 @@ export interface ModuleInstance {
   _type: 'module-instance';
   id: string;
   mount: string;
+  /** When false, karaoke() skips route injection and menu entries for this module. Defaults to true. */
+  enabled: boolean;
   routes: Array<{ pattern: string; entrypoint: string }>;
   menuEntries: ModuleMenuEntry[];
   cssContract: readonly string[];
   hasDefaultCss: boolean;
+  /**
+   * Page files to copy into the user's src/pages/ on first dev run.
+   * Only copied if the destination does not already exist.
+   * src: absolute path to the source .astro file in the npm package.
+   * dest: path relative to src/pages/ (e.g. "blog/index.astro").
+   */
+  scaffoldPages?: Array<{ src: string; dest: string }>;
+  /**
+   * Absolute path to the module's default CSS file.
+   * On first dev run, copied to src/styles/{id}.css and imported into global.css.
+   */
+  defaultCssPath?: string;
 }
 
 /** A resolved theme instance — returned by a defineTheme() factory. */
@@ -135,5 +150,6 @@ export interface ThemeInstance {
   _type: 'theme-instance';
   id: string;
   implementedModuleIds: string[];
+  implementedModules: ModuleInstance[];
   toAstroIntegration: () => import('astro').AstroIntegration;
 }

package/src/utils/resolve-menus.ts

@@ -1,7 +1,7 @@
 import { readFileSync } from 'fs';
 import { join } from 'path';
 import { parse } from 'yaml';
-import type { MenuConfig, MenuEntryConfig, ResolvedMenuEntry, ResolvedMenu, ResolvedMenus } from '../types.js';
+import type { MenuConfig, MenuEntryConfig, ResolvedMenuEntry, ResolvedMenu, ResolvedMenus, ModuleInstance } from '../types.js';
 
 /** Reject javascript: and data: hrefs to prevent stored XSS via menus.yaml. */
 function sanitizeHref(href: string): string | undefined {
@@ -24,25 +24,66 @@ function normalizeEntries(raw: MenuEntryConfig[], depth = 0): ResolvedMenuEntry[
     .sort((a, b) => a.weight - b.weight);
 }
 
-function defaultMain(): ResolvedMenu {
+function defaultMain(modules: ModuleInstance[]): ResolvedMenu {
+  // Resolve href for module entries: path '/' means the module's mount root.
+  const moduleMainEntries: ResolvedMenuEntry[] = modules
+    .flatMap(m => m.menuEntries
+      .filter(e => e.section === 'main')
+      .map(e => ({
+        text: e.name,
+        href: e.path === '/' ? m.mount : e.path,
+        weight: e.weight,
+        when: `collection:${m.id}`,
+        entries: [] as ResolvedMenuEntry[],
+      }))
+    );
+
+  // Theme-owned entries (Docs, Tags) are always present.
+  const themeEntries: ResolvedMenuEntry[] = [
+    { text: 'Docs', href: '/docs', weight: 20, when: 'collection:docs', entries: [] },
+    { text: 'Tags', href: '/tags', weight: 30, entries: [] },
+  ];
+
+  // If no modules provide main entries, fall back to hardcoded Blog default.
+  const mainEntries =
+    moduleMainEntries.length > 0
+      ? [...moduleMainEntries, ...themeEntries]
+      : [
+          { text: 'Blog', href: '/blog', weight: 10, when: 'collection:blog', entries: [] },
+          ...themeEntries,
+        ];
+
   return {
     name: 'main',
     orientation: 'horizontal',
-    entries: [
-      { text: 'Blog', href: '/blog', weight: 10, when: 'collection:blog', entries: [] },
-      { text: 'Docs', href: '/docs', weight: 20, when: 'collection:docs', entries: [] },
-      { text: 'Tags', href: '/tags', weight: 30, entries: [] },
-    ],
+    entries: mainEntries.sort((a, b) => a.weight - b.weight),
   };
 }
 
-function defaultFooter(): ResolvedMenu {
+function defaultFooter(modules: ModuleInstance[]): ResolvedMenu {
+  // Derive RSS-like entries from modules' footer-section menuEntries.
+  const moduleFooterEntries: ResolvedMenuEntry[] = modules
+    .flatMap(m => m.menuEntries
+      .filter(e => e.section === 'footer')
+      .map(e => ({
+        text: e.name,
+        href: e.path === '/' ? m.mount : e.path,
+        weight: e.weight,
+        when: undefined,
+        entries: [] as ResolvedMenuEntry[],
+      }))
+    );
+
+  // Fall back to hardcoded /rss.xml if no module provides a footer entry.
+  const footerEntries =
+    moduleFooterEntries.length > 0
+      ? moduleFooterEntries
+      : [{ text: 'RSS', href: '/rss.xml', weight: 10, entries: [] }];
+
   return {
     name: 'footer',
     orientation: 'horizontal',
-    entries: [
-      { text: 'RSS', href: '/rss.xml', weight: 10, entries: [] },
-    ],
+    entries: footerEntries,
   };
 }
 
@@ -54,14 +95,14 @@ function defaultFooter(): ResolvedMenu {
  * to render. ENOENT (no menus.yaml) is the normal zero-config case; all other
  * errors warn and fall back to defaults.
  */
-export function resolveMenus(vaultDir: string): ResolvedMenus {
+export function resolveMenus(vaultDir: string, modules: ModuleInstance[] = []): ResolvedMenus {
   try {
     const path = join(vaultDir, 'karaoke-cms/config/menus.yaml');
     const raw = readFileSync(path, 'utf8');
     const parsed = parse(raw) as { menus?: Record<string, MenuConfig> };
 
     if (!parsed?.menus || typeof parsed.menus !== 'object') {
-      return { main: defaultMain(), footer: defaultFooter() };
+      return { main: defaultMain(modules), footer: defaultFooter(modules) };
     }
 
     const result: ResolvedMenus = {};
@@ -81,8 +122,8 @@ export function resolveMenus(vaultDir: string): ResolvedMenus {
         entries: normalizeEntries(cfg?.entries ?? []),
       };
     }
-    if (!result.main) result.main = defaultMain();
-    if (!result.footer) result.footer = defaultFooter();
+    if (!result.main) result.main = defaultMain(modules);
+    if (!result.footer) result.footer = defaultFooter(modules);
     return result;
   } catch (err: unknown) {
     if ((err as NodeJS.ErrnoException).code !== 'ENOENT') {
@@ -90,6 +131,6 @@ export function resolveMenus(vaultDir: string): ResolvedMenus {
         `[karaoke-cms] Failed to parse menus.yaml: ${(err as Error).message}. Using default menus.`,
       );
     }
-    return { main: defaultMain(), footer: defaultFooter() };
+    return { main: defaultMain(modules), footer: defaultFooter(modules) };
   }
 }

package/src/utils/resolve-modules.ts

@@ -1,20 +1,16 @@
-// Minimal config shape — mirrors KaraokeConfig.modules without importing from root
+// Minimal config shape — mirrors KaraokeConfig.comments without importing from root
 // so this utility stays self-contained and testable.
 export interface ModuleConfig {
-  modules?: {
-    search?: { enabled?: boolean };
-    comments?: {
-      enabled?: boolean;
-      repo?: string;
-      repoId?: string;
-      category?: string;
-      categoryId?: string;
-    };
+  comments?: {
+    enabled?: boolean;
+    repo?: string;
+    repoId?: string;
+    category?: string;
+    categoryId?: string;
   };
 }
 
 export interface ResolvedModules {
-  search: { enabled: boolean };
   comments: {
     enabled: boolean;
     repo: string;
@@ -26,15 +22,12 @@ export interface ResolvedModules {
 
 export function resolveModules(config: ModuleConfig | null | undefined): ResolvedModules {
   return {
-    search: {
-      enabled: config?.modules?.search?.enabled ?? false,
-    },
     comments: {
-      enabled: config?.modules?.comments?.enabled ?? false,
-      repo: config?.modules?.comments?.repo ?? '',
-      repoId: config?.modules?.comments?.repoId ?? '',
-      category: config?.modules?.comments?.category ?? '',
-      categoryId: config?.modules?.comments?.categoryId ?? '',
+      enabled: config?.comments?.enabled ?? false,
+      repo: config?.comments?.repo ?? '',
+      repoId: config?.comments?.repoId ?? '',
+      category: config?.comments?.category ?? '',
+      categoryId: config?.comments?.categoryId ?? '',
     },
   };
 }

package/src/validate-config.js

@@ -11,14 +11,14 @@
  * @param {import('../karaoke.config').KaraokeConfig | null | undefined} config
  */
 export function validateModules(config) {
-  const comments = config?.modules?.comments
+  const comments = config?.comments
   if (!comments?.enabled) return
 
   const required = ['repo', 'repoId', 'category', 'categoryId']
   const missing = required.filter(k => !comments[k])
   if (missing.length > 0) {
     throw new Error(
-      `karaoke-cms: modules.comments.enabled is true but the following required fields are missing: ` +
+      `karaoke-cms: comments.enabled is true but the following required fields are missing: ` +
       `${missing.join(', ')}. Get these values from https://giscus.app`
     )
   }