@karaoke-cms/astro 0.6.3 → 0.9.1

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.1",
+  "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 test/define-module.test.js test/define-theme.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,21 @@
 ---
+import Menu from '../Menu.astro';
+import { siteTitle } from 'virtual:karaoke-cms/config';
 ---
-<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>
+<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),
+    };
+  };
+}