@karaoke-cms/astro 0.9.0 → 0.9.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@karaoke-cms/astro",
   "type": "module",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "description": "Core Astro integration for karaoke-cms — virtual config, wikilinks, handbook routes",
   "main": "./src/index.ts",
   "exports": {
@@ -41,6 +41,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": "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"
   }
 }

package/src/components/regions/SiteFooter.astro

@@ -1,7 +1,21 @@
 ---
 import Menu from '../Menu.astro';
+import { siteTitle } from 'virtual:karaoke-cms/config';
 ---
-<Menu name="footer" />
-<div class="footer-attr">
-  Built with <a href="https://karaoke-cms.org">karaoke-cms</a>
+<div class="footer-grid">
+  <div class="footer-col">
+    <p class="footer-brand">karaoke-cms</p>
+    <p class="footer-tagline">An Astro framework for publishing Obsidian vaults as private-by-default static sites.</p>
+  </div>
+  <div class="footer-col">
+    <Menu name="footer-2" />
+  </div>
+  <div class="footer-col"></div>
+  <div class="footer-col">
+    <Menu name="footer" />
+  </div>
+</div>
+<div class="footer-below">
+  <span>&copy; {new Date().getFullYear()} {siteTitle}</span>
+  <span class="footer-attr">Built with <a href="https://karaoke-cms.org">karaoke-cms</a></span>
 </div>

package/src/define-module.ts

@@ -0,0 +1,38 @@
+import type { ModuleInstance, ModuleMenuEntry } from './types.js';
+
+export interface ModuleDefinition {
+  id: string;
+  cssContract: readonly string[];
+  defaultCss?: () => Promise<unknown>;
+  routes: (mount: string) => Array<{ pattern: string; entrypoint: string }>;
+  menuEntries: (mount: string, id: string) => ModuleMenuEntry[];
+  collection?: () => unknown;
+}
+
+/**
+ * Define a karaoke-cms module.
+ *
+ * Returns a factory function. Call the factory with `{ mount }` (and optionally
+ * `{ id }` for multi-instance support) to get a ModuleInstance that can be
+ * passed to `defineConfig({ modules: [...] })`.
+ *
+ * @example
+ * export const blog = defineModule({ id: 'blog', routes: (mount) => [...], ... })
+ * // In karaoke.config.ts:
+ * modules: [blog({ mount: '/blog' })]
+ */
+export function defineModule(def: ModuleDefinition) {
+  return function moduleFactory(config: { id?: string; mount: string }): ModuleInstance {
+    const id = config.id ?? def.id;
+    const mount = config.mount.replace(/\/$/, '');
+    return {
+      _type: 'module-instance',
+      id,
+      mount,
+      routes: def.routes(mount),
+      menuEntries: def.menuEntries(mount, id),
+      cssContract: def.cssContract,
+      hasDefaultCss: !!def.defaultCss,
+    };
+  };
+}

package/src/define-theme.ts

@@ -0,0 +1,37 @@
+import type { AstroIntegration } from 'astro';
+import type { ModuleInstance, ThemeInstance } from './types.js';
+
+export interface ThemeFactoryConfig {
+  implements?: ModuleInstance[];
+}
+
+export interface ThemeDefinition {
+  id: string;
+  toAstroIntegration: (config: ThemeFactoryConfig) => 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: ... })`.
+ *
+ * @example
+ * export const themeDefault = defineTheme({
+ *   id: 'theme-default',
+ *   toAstroIntegration: (config) => ({ name: '...', hooks: { ... } }),
+ * })
+ * // In karaoke.config.ts:
+ * theme: themeDefault({ implements: [blog({ mount: '/blog' })] })
+ */
+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),
+    };
+  };
+}

package/src/index.ts

@@ -9,7 +9,12 @@ 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 } from './types.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.
@@ -47,6 +52,11 @@ function resolveThemePkg(theme: string | undefined): string {
  *   integrations: [karaoke(karaokeConfig)],
  * });
  */
+/** Identity wrapper for karaoke.config.ts — provides type inference. */
+export function defineConfig(config: KaraokeConfig): KaraokeConfig {
+  return config;
+}
+
 export default function karaoke(config: KaraokeConfig = {}): AstroIntegration {
   validateModules(config);
   const resolved = resolveModules(config);
@@ -67,27 +77,34 @@ export default function karaoke(config: KaraokeConfig = {}): AstroIntegration {
         const _resolvedMenus = resolveMenus(vaultDir);
 
         // ── 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}`,
-          );
+        let themeIntegration: AstroIntegration;
+
+        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}`,
+            );
+          }
+          // 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);
         }
-        // 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' });
@@ -165,4 +182,7 @@ export const resolvedMenus = ${JSON.stringify(resolvedMenus)};
   };
 }
 
+export { defineModule } from './define-module.js';
+export { defineTheme } from './define-theme.js';
+export type { ModuleInstance, ThemeInstance, ModuleMenuEntry } from './types.js';
 export type { KaraokeConfig, ResolvedModules, ResolvedLayout, ResolvedCollections, RegionComponent, ResolvedMenus, ResolvedMenu, ResolvedMenuEntry } from './types.js';

package/src/types.ts

@@ -29,8 +29,8 @@ export interface KaraokeConfig {
   title?: string;
   /** Site description — used in RSS feed and OG meta tags. */
   description?: string;
-  /** Theme name — must match a folder in themes/. Defaults to 'default'. */
-  theme?: string;
+  /** Theme — package name string (legacy) or a ThemeInstance from defineTheme(). */
+  theme?: string | ThemeInstance;
   modules?: {
     search?: { enabled?: boolean };
     comments?: {
@@ -107,3 +107,33 @@ export interface ResolvedMenu {
 }
 
 export type ResolvedMenus = Record<string, ResolvedMenu>;
+
+// ── Module system types ────────────────────────────────────────────────────────
+
+/** A menu entry registered by a module instance. */
+export interface ModuleMenuEntry {
+  id: string;
+  name: string;
+  path: string;
+  section: string;
+  weight: number;
+}
+
+/** A resolved module instance — returned by a defineModule() factory. */
+export interface ModuleInstance {
+  _type: 'module-instance';
+  id: string;
+  mount: string;
+  routes: Array<{ pattern: string; entrypoint: string }>;
+  menuEntries: ModuleMenuEntry[];
+  cssContract: readonly string[];
+  hasDefaultCss: boolean;
+}
+
+/** A resolved theme instance — returned by a defineTheme() factory. */
+export interface ThemeInstance {
+  _type: 'theme-instance';
+  id: string;
+  implementedModuleIds: string[];
+  toAstroIntegration: () => import('astro').AstroIntegration;
+}