@karaoke-cms/astro 0.9.8 → 0.10.3

package/README.md

@@ -1,6 +1,6 @@
 # @karaoke-cms/astro
 
-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.
+Core Astro integration for karaoke-cms. Wires up themes, modules, collections, menus, Obsidian embed handling, and the virtual config module at build time. Every karaoke-cms project depends on this package.
 
 ## Installation
 
@@ -57,6 +57,56 @@ All fields are optional. Defaults produce a working site with no content.
 | `collections` | `Record<string, CollectionConfig>` | — | Per-collection mode overrides |
 | `layout.regions` | `{ top, left, right, bottom }` | — | Region component lists |
 
+## Obsidian embed syntax
+
+Markdown files can use Obsidian's `![[file]]` embed syntax. The integration handles it automatically:
+
+### Image embeds
+
+```markdown
+![[photo.jpg]]           — embedded image (Astro-optimized)
+![[photo.jpg|300]]       — image with width hint → <img width="300">
+![[photo.jpg|300x200]]   — image with width and height → <img width="300" height="200">
+![[photo.jpg|alt text]]  — image with alt text
+```
+
+Image files are resolved in this order:
+1. Same folder as the note
+2. Vault `attachmentFolderPath` from `.obsidian/app.json`
+3. Vault root
+
+Resolved images go through Astro's image optimisation pipeline.
+
+### Audio and video embeds
+
+```markdown
+![[recording.mp3]]   — → <audio controls>
+![[clip.mp4]]        — → <video controls>
+```
+
+Audio and video files are served from `/media/` in dev and copied to `dist/media/` at build time.
+
+### Wiki links in `featured_image` frontmatter
+
+```yaml
+featured_image: "[[hero.jpg]]"
+```
+
+The wiki link is resolved using the same vault path lookup as inline embeds and rewritten to `/media/hero.jpg`. Use `resolveWikiImage()` in your templates — see below.
+
+## `resolveWikiImage(value)`
+
+A utility for templates that render `featured_image`. Call it on the raw frontmatter value — it rewrites `[[file.jpg]]` to `/media/file.jpg` and passes regular paths and URLs through unchanged.
+
+```ts
+import { resolveWikiImage } from '@karaoke-cms/astro';
+
+// In an Astro template:
+<img src={resolveWikiImage(entry.data.featured_image)} alt={entry.data.title} />
+```
+
+This is necessary because Astro sets `entry.data` from validated frontmatter at collection-load time, before the remark plugin runs. Templates must call `resolveWikiImage()` to get the resolved URL.
+
 ## Exports
 
 ### `@karaoke-cms/astro` — main integration
@@ -65,6 +115,7 @@ All fields are optional. Defaults produce a working site with no content.
 - `defineConfig(config)` — identity wrapper for type inference
 - `defineModule(def)` — create a module factory
 - `defineTheme(def)` — create a theme factory
+- `resolveWikiImage(value)` — resolve `[[wiki link]]` to `/media/` URL for use in templates
 
 ### `@karaoke-cms/astro/env`
 
@@ -116,6 +167,29 @@ layout: {
 
 Available components: `'header'`, `'main-menu'`, `'search'`, `'recent-posts'`, `'footer'`.
 
+## What's new in 0.10.3
+
+- **Vault path warning** — if `KARAOKE_VAULT` points to a directory that doesn't exist, a clear warning is printed at startup instead of silently building a site with empty collections. The message shows the resolved path and points to `.env` / `.env.default`.
+- **`menus.yaml` live reload** — editing `{vault}/karaoke-cms/config/menus.yaml` while the dev server is running now triggers an immediate full-page reload. No more restarting `npm run dev` after menu changes.
+- **Security: path traversal guard hardened** — the docs codegen path-traversal check now uses `path.normalize()` on both sides of the comparison, so the guard holds correctly on Windows and with symlinked paths.
+
+## What's new in 0.10.2
+
+- **Multiple named docs sections** — run `docs({ mount: '/api-docs', folder: 'api-reference', label: 'API Reference' })` alongside `docs({ mount: '/docs' })`. Each section gets its own sidebar, URL space, and Astro content collection. Routes are code-generated per instance at build time.
+- **Auto-registered docs collections** — pass your full config to `makeCollections({ config })` in `content.config.ts` and all docs instances register automatically. No manual sync required when adding a second section.
+- **`virtual:karaoke-cms/docs-sections`** — new Vite virtual module exporting all active docs section specs. Import it in any page to build section switchers or cross-section links.
+- **Section switcher in doc pages** — when two or more docs sections are active, a nav row lists them with the current one highlighted.
+- **Tags and RSS are section-aware** — `/tags`, `/tags/[tag]`, and `/rss.xml` now aggregate entries from every active docs section.
+- **Fix: dev-only collection menu entries** — entries with `when: collection:name` now correctly show in dev mode when the collection exists but has no published entries.
+
+## What's new in 0.10.0
+
+- **Obsidian `![[image]]` embed support** — `![[photo.jpg]]` in any markdown note is resolved via vault path lookup and goes through Astro's image optimisation pipeline
+- **Size hints** — `![[photo.jpg|300]]` sets `width="300"`; `![[photo.jpg|300x200]]` sets both width and height
+- **Audio and video embeds** — `![[recording.mp3]]` → `<audio controls>`, `![[clip.mp4]]` → `<video controls>`; files served from `/media/` in dev, emitted to `dist/media/` at build
+- **`featured_image` wiki link support** — `featured_image: "[[hero.jpg]]"` in frontmatter is resolved to `/media/hero.jpg` via vault path lookup
+- **`resolveWikiImage(value)` export** — utility for templates to rewrite `[[file.jpg]]` frontmatter values to the correct `/media/` URL at render time
+
 ## What's new in 0.9.5
 
 - **`isThemeInstance` type-guard** added — fixes a runtime crash in the `astro:config:setup` hook when a `ThemeInstance` was passed

package/client.d.ts

@@ -6,7 +6,7 @@
  */
 
 declare module 'virtual:karaoke-cms/config' {
-  import type { ResolvedModules, ResolvedLayout, ResolvedCollections, ResolvedMenus } from '@karaoke-cms/astro';
+  import type { ResolvedModules, ResolvedLayout, ResolvedCollections, ResolvedMenus } from '@karaoke-cms/contracts';
 
   /** Site title from karaoke.config.ts */
   export const siteTitle: string;
@@ -23,3 +23,16 @@ declare module 'virtual:karaoke-cms/config' {
   /** Mount path of the blog module (e.g. '/blog' or '/news'). Defaults to '/blog'. */
   export const blogMount: string;
 }
+
+declare module 'virtual:karaoke-cms/docs-sections' {
+  /** All active docs module instances, in declaration order. */
+  export const docsSections: Array<{
+    id: string;
+    collection: string;
+    mount: string;
+    folder: string;
+    label: string;
+    layout: string;
+    sidebarStyle: string;
+  }>;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@karaoke-cms/astro",
   "type": "module",
-  "version": "0.9.8",
+  "version": "0.10.3",
   "description": "Core Astro integration for karaoke-cms — virtual config, wikilinks, handbook routes",
   "main": "./src/index.ts",
   "exports": {
@@ -36,13 +36,14 @@
     "@astrojs/sitemap": "^3.7.1",
     "remark-wiki-link": "^2.0.1",
     "yaml": "^2.7.0",
-    "zod": "^4.0.0"
+    "zod": "^4.0.0",
+    "@karaoke-cms/contracts": "0.10.3"
   },
   "devDependencies": {
     "vitest": "^4.1.1",
     "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/theme-default-styles.test.js test/module-injection.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 test/codegen-docs.test.js test/codegen-snapshot.test.js"
   }
-}
+}

package/src/codegen/generate-docs-instance.ts

@@ -0,0 +1,210 @@
+import { mkdirSync, writeFileSync, rmSync, existsSync } from 'fs';
+import { join, normalize, sep } from 'path';
+import { pathToFileURL } from 'url';
+
+export interface DocsInstanceSpec {
+  id: string;
+  collection: string;
+  mount: string;
+  folder: string;
+  label: string;
+  layout: string;
+  sidebarStyle: string;
+}
+
+/**
+ * Generate per-instance .astro page files for all active docs instances.
+ *
+ * Each instance gets three files written to:
+ *   {rootDir}/.astro/generated/karaoke-cms/{id}/doc.astro
+ *   {rootDir}/.astro/generated/karaoke-cms/{id}/home.astro
+ *   {rootDir}/.astro/generated/karaoke-cms/{id}/list.astro
+ *
+ * The generated root is wiped on every call so stale files from removed
+ * instances are automatically cleaned up.
+ *
+ * @returns Array of { pattern, entrypoint } ready to pass to injectRoute().
+ */
+export function generateDocsInstancePages(
+  rootDir: string,
+  instances: DocsInstanceSpec[],
+): Array<{ pattern: string; entrypoint: string }> {
+  const generatedRoot = join(rootDir, '.astro', 'generated', 'karaoke-cms');
+
+  // Always wipe the generated root so stale files from removed instances are cleaned up.
+  if (existsSync(generatedRoot)) {
+    rmSync(generatedRoot, { recursive: true, force: true });
+  }
+
+  if (instances.length === 0) return [];
+
+  mkdirSync(generatedRoot, { recursive: true });
+
+  const routes: Array<{ pattern: string; entrypoint: string }> = [];
+
+  for (const inst of instances) {
+    const dir = join(generatedRoot, inst.id);
+    // Guard against path traversal via a malicious id (e.g., '../../evil').
+    // normalize() resolves '..' segments before comparison so the check holds on
+    // all platforms and with symlinks in the path.
+    const normalizedDir = normalize(dir);
+    const normalizedRoot = normalize(generatedRoot);
+    if (!normalizedDir.startsWith(normalizedRoot + sep) && normalizedDir !== normalizedRoot) {
+      throw new Error(`[karaoke-cms] docs() id "${inst.id}" resolves outside the generated root. Use a simple identifier without path separators.`);
+    }
+    mkdirSync(dir, { recursive: true });
+
+    writeFileSync(join(dir, 'doc.astro'), generateDocPage(inst), 'utf8');
+    writeFileSync(join(dir, 'home.astro'), generateHomePage(inst), 'utf8');
+    writeFileSync(join(dir, 'list.astro'), generateListPage(inst), 'utf8');
+
+    routes.push(
+      { pattern: `${inst.mount}/[slug]`, entrypoint: pathToFileURL(join(dir, 'doc.astro')).href },
+      { pattern: inst.mount || '/',       entrypoint: pathToFileURL(join(dir, 'home.astro')).href },
+      { pattern: `${inst.mount}/list`,    entrypoint: pathToFileURL(join(dir, 'list.astro')).href },
+    );
+  }
+
+  return routes;
+}
+
+export function generateDocPage(inst: DocsInstanceSpec): string {
+  return `---
+// AUTO-GENERATED by karaoke-cms — do not edit directly.
+// Re-generated on each dev/build start. Source: packages/astro/src/codegen/generate-docs-instance.ts
+const section = ${JSON.stringify(inst)};
+import { getCollection, render } from 'astro:content';
+import DefaultPage from '@karaoke-cms/astro/layouts/DefaultPage.astro';
+import ModuleLoader from '@karaoke-cms/astro/components/ModuleLoader.astro';
+import { siteTitle } from 'virtual:karaoke-cms/config';
+import { docsSections } from 'virtual:karaoke-cms/docs-sections';
+import { resolveWikiImage } from '@karaoke-cms/astro';
+
+export async function getStaticPaths() {
+  // Use a string literal here — module-scope const is not accessible inside
+  // getStaticPaths after Astro/Vite extraction in production builds.
+  const docs = await getCollection(${JSON.stringify(inst.collection)}, ({ data }) => data.publish === true);
+  return docs.map(entry => ({
+    params: { slug: entry.id },
+    props: { entry },
+  }));
+}
+
+const { entry } = Astro.props;
+const { Content } = await render(entry);
+
+const allDocs = (await getCollection(${JSON.stringify(inst.collection)}, ({ data }) => data.publish === true))
+  .sort((a, b) => a.data.title.localeCompare(b.data.title));
+---
+
+<DefaultPage title={\`\${entry.data.title} — \${siteTitle}\`} description={entry.data.description} type="article">
+  {docsSections.length > 1 && (
+    <nav class="docs-section-switcher" slot="left">
+      {docsSections.map(s => (
+        <a href={s.mount} class={\`docs-section-link\${s.id === section.id ? ' active' : ''}\`}>
+          {s.label}
+        </a>
+      ))}
+    </nav>
+  )}
+  <nav class="docs-sidebar" slot="left">
+    <ul class="docs-sidebar-list">
+      {allDocs.map(doc => (
+        <li class="docs-sidebar-item">
+          <a href={\`\${section.mount}/\${doc.id}\`} aria-current={doc.id === entry.id ? 'page' : undefined}>
+            {doc.data.title}
+          </a>
+        </li>
+      ))}
+    </ul>
+  </nav>
+  <article class="docs-article">
+    {entry.data.featured_image && (
+      <img src={resolveWikiImage(entry.data.featured_image)} alt="" class="docs-article-image" />
+    )}
+    <h1 class="docs-article-title">{entry.data.title}</h1>
+    {entry.data.tags && entry.data.tags.length > 0 && (
+      <div class="docs-tag-list docs-article-meta">
+        {entry.data.tags.map(tag => (
+          <a href={\`/tags/\${tag}\`} class="docs-tag">#{tag}</a>
+        ))}
+      </div>
+    )}
+    <div class="prose">
+      <Content />
+    </div>
+  </article>
+  <ModuleLoader comments={entry.data.comments} />
+</DefaultPage>
+`;
+}
+
+export function generateHomePage(inst: DocsInstanceSpec): string {
+  return `---
+// AUTO-GENERATED by karaoke-cms — do not edit directly.
+// Re-generated on each dev/build start. Source: packages/astro/src/codegen/generate-docs-instance.ts
+const section = ${JSON.stringify(inst)};
+import { getCollection } from 'astro:content';
+import DefaultPage from '@karaoke-cms/astro/layouts/DefaultPage.astro';
+import { siteTitle } from 'virtual:karaoke-cms/config';
+
+const docs = (await getCollection(${JSON.stringify(inst.collection)}, ({ data }) => data.publish === true))
+  .sort((a, b) => a.data.title.localeCompare(b.data.title));
+---
+
+<DefaultPage title={\`\${section.label} — \${siteTitle}\`}>
+  <div class="docs-home">
+    <h1>{section.label}</h1>
+    {docs.length > 0 ? (
+      <ul class="docs-home-list">
+        {docs.map(doc => (
+          <li class="docs-home-item">
+            <a href={\`\${section.mount}/\${doc.id}\`}>{doc.data.title}</a>
+          </li>
+        ))}
+      </ul>
+    ) : (
+      <div class="empty-state">
+        <p>No docs published yet.</p>
+        <p>Create a Markdown file in your vault's <code>{section.folder}/</code> folder and set <code>publish: true</code> in the frontmatter to make it appear here.</p>
+      </div>
+    )}
+  </div>
+</DefaultPage>
+`;
+}
+
+export function generateListPage(inst: DocsInstanceSpec): string {
+  return `---
+// AUTO-GENERATED by karaoke-cms — do not edit directly.
+// Re-generated on each dev/build start. Source: packages/astro/src/codegen/generate-docs-instance.ts
+const section = ${JSON.stringify(inst)};
+import { getCollection } from 'astro:content';
+import DefaultPage from '@karaoke-cms/astro/layouts/DefaultPage.astro';
+import { siteTitle } from 'virtual:karaoke-cms/config';
+
+const docs = (await getCollection(${JSON.stringify(inst.collection)}, ({ data }) => data.publish === true))
+  .sort((a, b) => a.data.title.localeCompare(b.data.title));
+---
+
+<DefaultPage title={\`All \${section.label} — \${siteTitle}\`}>
+  <div class="docs-list">
+    <h1>All {section.label}</h1>
+    {docs.length > 0 ? (
+      <ul>
+        {docs.map(doc => (
+          <li class="docs-list-item">
+            <a href={\`\${section.mount}/\${doc.id}\`}>{doc.data.title}</a>
+          </li>
+        ))}
+      </ul>
+    ) : (
+      <div class="empty-state">
+        <p>No docs published yet.</p>
+        <p>Create a Markdown file in your vault's <code>{section.folder}/</code> folder and set <code>publish: true</code> in the frontmatter to make it appear here.</p>
+      </div>
+    )}
+  </div>
+</DefaultPage>
+`;
+}

package/src/collections.ts

@@ -3,7 +3,11 @@ import { glob } from 'astro/loaders';
 import { fileURLToPath } from 'url';
 import { join, resolve, isAbsolute } from 'path';
 import { resolveCollections } from './utils/resolve-collections.js';
-import type { CollectionConfig } from './types.js';
+import type { CollectionConfig, KaraokeConfig, ModuleInstance, ThemeInstance } from './types.js';
+
+function isThemeInstance(theme: unknown): theme is ThemeInstance {
+  return typeof theme === 'object' && theme !== null && (theme as ThemeInstance)._type === 'theme-instance';
+}
 export { blogThemeExtension } from './blog-schema.js';
 
 const baseSchema = z.object({
@@ -36,6 +40,11 @@ export interface MakeCollectionsOptions {
   collections?: Record<string, CollectionConfig>;
   /** Zod schema extension merged into the blog collection schema. Use with @karaoke-cms/theme-blog. */
   blogSchema?: z.ZodObject<z.ZodRawShape>;
+  /**
+   * Full karaoke config. When provided, Astro collections are auto-registered
+   * for every docs() instance declared in config.modules and theme.implementedModules.
+   */
+  config?: KaraokeConfig;
 }
 
 /**
@@ -114,5 +123,28 @@ export function makeCollections(
     }
   }
 
+  // Register collections for docs() instances from config.modules and theme.implementedModules.
+  // Skip if already registered by the hardcoded blocks above (hardcoded schema wins for 'docs').
+  if (opts?.config) {
+    const configMods: ModuleInstance[] = opts.config.modules ?? [];
+    const themeMods: ModuleInstance[] = isThemeInstance(opts.config.theme)
+      ? (opts.config.theme.implementedModules ?? [])
+      : [];
+    const seenCollections = new Set(Object.keys(collections));
+    for (const mod of [...configMods, ...themeMods]) {
+      if (!mod.collection || mod.enabled === false) continue;
+      const name = mod.collection.name;
+      if (seenCollections.has(name)) continue;
+      seenCollections.add(name);
+      collections[name] = defineCollection({
+        loader: glob({ pattern: '**/*.md', base: join(vaultDir, mod.collection.folder) }),
+        schema: baseSchema.extend({
+          featured_image: z.string().optional(),
+          comments: z.boolean().optional().default(false),
+        }),
+      });
+    }
+  }
+
   return collections;
 }

package/src/components/Menu.astro

@@ -36,7 +36,7 @@ async function isVisible(entry: ResolvedMenuEntry): Promise<boolean> {
       // 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);
+      const entries = await getCollection(colName as any, import.meta.env.PROD ? ({ data }: any) => data.publish === true : undefined);
       collectionEmpty[colName] = entries.length === 0;
     } catch {
       collectionEmpty[colName] = true;

package/src/components/regions/RecentPosts.astro

@@ -1,14 +1,17 @@
 ---
 import { getCollection } from 'astro:content';
+import { docsSections } from 'virtual:karaoke-cms/docs-sections';
 
 const LIMIT = 5;
 
-// Detect which collection we're in and exclude the current page
+// Detect which section we're in and exclude the current page
 const pathname = Astro.url.pathname.replace(/\/$/, '');
-const collection = pathname.startsWith('/docs/') ? 'docs' : 'blog';
+const matchedSection = docsSections.find(s => pathname === s.mount || pathname.startsWith(s.mount + '/'));
+const collection = matchedSection ? matchedSection.collection : 'blog';
+const mount = matchedSection ? matchedSection.mount : '/blog';
 const currentSlug = pathname.split('/').at(-1) ?? '';
 
-const posts = (await getCollection(collection, ({ data }) => data.publish === true))
+const posts = (await getCollection(collection as any, ({ data }) => data.publish === true))
   .sort((a, b) => (b.data.date?.valueOf() ?? 0) - (a.data.date?.valueOf() ?? 0))
   .filter(post => post.id !== currentSlug)
   .slice(0, LIMIT);
@@ -20,7 +23,7 @@ const posts = (await getCollection(collection, ({ data }) => data.publish === tr
     <ul class="sidebar-list">
       {posts.map(post => (
         <li>
-          <a href={`/${collection}/${post.id}`}>{post.data.title}</a>
+          <a href={`${mount}/${post.id}`}>{post.data.title}</a>
           {post.data.date && (
             <span class="post-date">{post.data.date.toISOString().slice(0, 10)}</span>
           )}

package/src/components/regions/SiteFooter.astro

@@ -11,7 +11,9 @@ import pkg from '../../../package.json';
   <div class="footer-col">
     <Menu name="footer-2" />
   </div>
-  <div class="footer-col"></div>
+  <div class="footer-col">
+    <Menu name="footer-3" />
+  </div>
   <div class="footer-col">
     <Menu name="footer" />
   </div>

package/src/define-module.ts

@@ -1,48 +1,3 @@
-import type { ModuleInstance, ModuleMenuEntry } from './types.js';
-
-export interface ModuleDefinition {
-  id: string;
-  cssContract: readonly string[];
-  /** 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 }>;
-}
-
-/**
- * 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; 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.defaultCssPath,
-      scaffoldPages: def.scaffoldPages?.(mount),
-      defaultCssPath: def.defaultCssPath,
-    };
-  };
-}
+// defineModule() and ModuleDefinition now live in @karaoke-cms/contracts.
+// Re-exported here so internal callers (index.ts) are unaffected.
+export { defineModule, type ModuleDefinition } from '@karaoke-cms/contracts';

package/src/define-theme.ts

@@ -1,34 +1,3 @@
-import type { AstroIntegration } from 'astro';
-import type { ModuleInstance, ThemeInstance } from './types.js';
-
-export interface ThemeFactoryConfig {}
-
-export interface ThemeDefinition {
-  id: string;
-  toAstroIntegration: (config: ThemeFactoryConfig, modules: ModuleInstance[]) => AstroIntegration;
-}
-
-/**
- * Define a karaoke-cms 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, modules) => ({ name: '...', hooks: { ... } }),
- * })
- * // In karaoke.config.ts:
- * theme: themeDefault()
- */
-export function defineTheme(def: ThemeDefinition) {
-  return function themeFactory(config: ThemeFactoryConfig = {}): ThemeInstance {
-    return {
-      _type: 'theme-instance',
-      id: def.id,
-      toAstroIntegration: (modules: ModuleInstance[]) => def.toAstroIntegration(config, modules),
-    };
-  };
-}
+// defineTheme(), ThemeDefinition, and ThemeFactoryConfig now live in @karaoke-cms/contracts.
+// Re-exported here so internal callers (index.ts) are unaffected.
+export { defineTheme, type ThemeDefinition, type ThemeFactoryConfig } from '@karaoke-cms/contracts';