@tenphi/cookbook 0.18.1 → 0.19.0

package/README.md

@@ -43,7 +43,7 @@ See [Theme and components](./docs/theme-and-components.md) for all named
 sub-elements and the custom component flow.
 
 Without configuration, a root `README.md` becomes `/` and
-`docs/**/*.{md,mdx}` supplies the remaining pages. Cookbook includes Starlight,
+`docs/**/*.{md,mdx}` supplies the remaining pages. Cookbook includes its Astro renderer,
 generates only static output, and derives its URL base from Astro. Adding other
 Astro content collections does not require a Cookbook collection adapter.
 

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { resolveDocsTheme } from "@tenphi/starlight";
+import { resolveDocsTheme } from "@tenphi/renderer";
 import { createDocsGraph, formatDiagnostics, materializePackage, normalizeDocsConfig, readDocsLock, reconcileDocsLock, resolveDocsProject, validateBuiltDocs, validateProjectAssets, writeDocsLock } from "@tenphi/docs";
 import { cp, mkdir } from "node:fs/promises";
 import { dirname, resolve } from "node:path";

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","names":[],"sources":["../src/cli.ts"],"sourcesContent":["import { cp, mkdir } from \"node:fs/promises\";\nimport { dirname, resolve } from \"node:path\";\nimport { parseArgs } from \"node:util\";\nimport {\n  createDocsGraph,\n  formatDiagnostics,\n  materializePackage,\n  normalizeDocsConfig,\n  readDocsLock,\n  reconcileDocsLock,\n  resolveDocsProject,\n  writeDocsLock,\n  validateProjectAssets,\n  validateBuiltDocs,\n  type DocsDiagnostic,\n  type DocsProject,\n} from \"@tenphi/docs\";\nimport { resolveDocsTheme } from \"@tenphi/starlight\";\n\nlet jsonOutput = process.argv.slice(2).includes(\"--json\");\n\ntry {\n  const { positionals, values } = parseArgs({\n    allowPositionals: true,\n    options: {\n      json: { type: \"boolean\", default: false },\n      root: { type: \"string\" },\n      config: { type: \"string\" },\n      out: { type: \"string\" },\n      url: { type: \"string\" },\n      \"public-dir\": { type: \"string\" },\n      \"dry-run\": { type: \"boolean\", default: false },\n      help: { type: \"boolean\", short: \"h\", default: false },\n    },\n  });\n  jsonOutput = values.json;\n  if (values.help || positionals.length === 0) {\n    printHelp();\n  } else {\n    const command = positionals[0];\n    if (![\"doctor\", \"update\", \"check-build\"].includes(command!)) {\n      throw new Error(`Unknown command: ${command ?? \"\"}.`);\n    }\n    if (command !== \"update\" && (positionals.length > 1 || values[\"dry-run\"])) {\n      throw new Error(\n        `${command} does not accept package selectors or --dry-run.`,\n      );\n    }\n    if (command !== \"check-build\" && (values.out || values.url))\n      throw new Error(\"--out and --url are only supported by check-build.\");\n    if (values[\"public-dir\"] && command !== \"doctor\")\n      throw new Error(\"--public-dir is only supported by doctor.\");\n    const project = await resolveDocsProject({\n      root: resolve(values.root ?? process.cwd()),\n      ...(values.config ? { configFile: values.config } : {}),\n    });\n    if (command === \"doctor\")\n      await doctor(\n        project,\n        values.json,\n        values[\"public-dir\"]\n          ? resolve(values.root ?? process.cwd(), values[\"public-dir\"])\n          : resolve(values.root ?? process.cwd(), \"public\"),\n      );\n    else if (command === \"check-build\") {\n      const graph = await createDocsGraph(project);\n      const report = await validateBuiltDocs({\n        directory: resolve(values.root ?? process.cwd(), values.out ?? \"dist\"),\n        graph,\n        ...(values.url ? { deployedUrl: values.url } : {}),\n      });\n      report.diagnostics.unshift(...graph.diagnostics);\n      report.ok = !report.diagnostics.some((d) => d.severity === \"error\");\n      if (values.json) console.log(JSON.stringify(report, null, 2));\n      else {\n        if (report.diagnostics.length)\n          console.log(formatDiagnostics(report.diagnostics));\n        console.log(\n          `${report.ok ? \"Passed\" : \"Failed\"} ${report.scope} checks: ${report.pages} pages, ${report.assets} assets${report.checkedUrls ? `, ${report.checkedUrls} deployed URLs` : \"\"}.`,\n        );\n      }\n      if (!report.ok) process.exitCode = 1;\n    } else\n      await update(\n        project,\n        positionals.slice(1),\n        values.json,\n        values[\"dry-run\"],\n      );\n  }\n} catch (error) {\n  const message = error instanceof Error ? error.message : String(error);\n  const diagnostics: DocsDiagnostic[] =\n    error && typeof error === \"object\" && \"diagnostics\" in error\n      ? (error.diagnostics as DocsDiagnostic[])\n      : [{ code: \"COOKBOOK_CLI_ERROR\", severity: \"error\", message }];\n  if (jsonOutput) {\n    console.log(\n      JSON.stringify({ ok: false, pages: 0, assets: 0, diagnostics }, null, 2),\n    );\n  } else {\n    console.error(formatDiagnostics(diagnostics));\n  }\n  process.exitCode = 1;\n}\n\nasync function doctor(\n  project: DocsProject,\n  json: boolean,\n  publicDirectory?: string,\n): Promise<void> {\n  const theme = resolveDocsTheme(project.config.theme);\n  const graph = await createDocsGraph(project);\n  const diagnostics = [\n    ...graph.diagnostics,\n    ...theme.diagnostics,\n    ...(await validateProjectAssets(project, graph, publicDirectory)),\n  ];\n  const hasErrors = diagnostics.some(\n    (diagnostic) => diagnostic.severity === \"error\",\n  );\n  if (json) {\n    console.log(\n      JSON.stringify(\n        {\n          ok: !hasErrors,\n          scope: \"preflight\",\n          buildVerified: false,\n          pages: graph.entries.length,\n          assets: graph.assets.length,\n          diagnostics,\n        },\n        null,\n        2,\n      ),\n    );\n  } else if (diagnostics.length > 0) {\n    console.log(formatDiagnostics(diagnostics));\n  } else {\n    console.log(\n      `Preflight passed: ${graph.entries.length} pages, ${graph.assets.length} content assets. MDX compilation, remote fonts, and deployment are not checked. Run astro build and cookbook check-build.`,\n    );\n  }\n  if (hasErrors) process.exitCode = 1;\n}\n\nasync function update(\n  project: DocsProject,\n  packages: string[],\n  json: boolean,\n  dryRun: boolean,\n): Promise<void> {\n  const existing = await readDocsLock(project.root);\n  const next = await reconcileDocsLock(project.config, existing, { packages });\n  const changes = next.sources.map((source) => ({\n    requested: source.requested,\n    from:\n      existing?.sources.find(\n        (current) => current.requested === source.requested,\n      )?.resolved ?? null,\n    to: source.resolved,\n  }));\n  const removed =\n    existing?.sources\n      .filter(\n        (source) =>\n          !next.sources.some(\n            (current) => current.requested === source.requested,\n          ),\n      )\n      .map((source) => source.requested) ?? [];\n  if (!dryRun) {\n    const build = normalizeDocsConfig(project.config).build;\n    for (const source of next.sources) {\n      if (!source.vendored) continue;\n      const current = existing?.sources.find(\n        (entry) => entry.requested === source.requested,\n      );\n      if (\n        current?.vendored === source.vendored &&\n        current.integrity === source.integrity\n      )\n        continue;\n      const { vendored, ...remote } = source;\n      const artifact = await materializePackage(remote, build, project.root);\n      const destination = resolve(project.root, vendored);\n      await mkdir(dirname(destination), { recursive: true });\n      await cp(artifact, destination, { recursive: true });\n    }\n    await writeDocsLock(project.root, next);\n  }\n  if (json) {\n    console.log(\n      JSON.stringify(\n        {\n          ok: true,\n          pages: 0,\n          assets: 0,\n          diagnostics: [],\n          dryRun,\n          changes,\n          removed,\n          lock: next,\n        },\n        null,\n        2,\n      ),\n    );\n  } else {\n    for (const change of changes)\n      console.log(\n        `${change.requested}: ${change.from ?? \"(new)\"} -> ${change.to}`,\n      );\n    for (const source of removed) console.log(`Removed ${source}`);\n    console.log(\n      dryRun\n        ? \"Dry run: cookbook.lock.json is unchanged.\"\n        : \"Updated cookbook.lock.json.\",\n    );\n  }\n}\n\nfunction printHelp(): never {\n  console.log(\n    `Usage: cookbook <command> [options]\\n\\nCommands:\\n  doctor             Check configuration, content graph, theme, and local files\\n  check-build        Inspect production output and optionally deployed URLs\\n  update [packages]  Reconcile configured package sources and their lock\\n\\nOptions:\\n  --root <directory>\\n  --config <path>\\n  --public-dir <directory>  Local public assets for doctor (default: public)\\n  --out <directory>        Built output (default: dist)\\n  --url <base-url>         Also check a deployed site\\n  --dry-run          Preview an update without writing files\\n  --json\\n  -h, --help`,\n  );\n  process.exit(0);\n}\n"],"mappings":"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"}
+{"version":3,"file":"cli.js","names":[],"sources":["../src/cli.ts"],"sourcesContent":["import { cp, mkdir } from \"node:fs/promises\";\nimport { dirname, resolve } from \"node:path\";\nimport { parseArgs } from \"node:util\";\nimport {\n  createDocsGraph,\n  formatDiagnostics,\n  materializePackage,\n  normalizeDocsConfig,\n  readDocsLock,\n  reconcileDocsLock,\n  resolveDocsProject,\n  writeDocsLock,\n  validateProjectAssets,\n  validateBuiltDocs,\n  type DocsDiagnostic,\n  type DocsProject,\n} from \"@tenphi/docs\";\nimport { resolveDocsTheme } from \"@tenphi/renderer\";\n\nlet jsonOutput = process.argv.slice(2).includes(\"--json\");\n\ntry {\n  const { positionals, values } = parseArgs({\n    allowPositionals: true,\n    options: {\n      json: { type: \"boolean\", default: false },\n      root: { type: \"string\" },\n      config: { type: \"string\" },\n      out: { type: \"string\" },\n      url: { type: \"string\" },\n      \"public-dir\": { type: \"string\" },\n      \"dry-run\": { type: \"boolean\", default: false },\n      help: { type: \"boolean\", short: \"h\", default: false },\n    },\n  });\n  jsonOutput = values.json;\n  if (values.help || positionals.length === 0) {\n    printHelp();\n  } else {\n    const command = positionals[0];\n    if (![\"doctor\", \"update\", \"check-build\"].includes(command!)) {\n      throw new Error(`Unknown command: ${command ?? \"\"}.`);\n    }\n    if (command !== \"update\" && (positionals.length > 1 || values[\"dry-run\"])) {\n      throw new Error(\n        `${command} does not accept package selectors or --dry-run.`,\n      );\n    }\n    if (command !== \"check-build\" && (values.out || values.url))\n      throw new Error(\"--out and --url are only supported by check-build.\");\n    if (values[\"public-dir\"] && command !== \"doctor\")\n      throw new Error(\"--public-dir is only supported by doctor.\");\n    const project = await resolveDocsProject({\n      root: resolve(values.root ?? process.cwd()),\n      ...(values.config ? { configFile: values.config } : {}),\n    });\n    if (command === \"doctor\")\n      await doctor(\n        project,\n        values.json,\n        values[\"public-dir\"]\n          ? resolve(values.root ?? process.cwd(), values[\"public-dir\"])\n          : resolve(values.root ?? process.cwd(), \"public\"),\n      );\n    else if (command === \"check-build\") {\n      const graph = await createDocsGraph(project);\n      const report = await validateBuiltDocs({\n        directory: resolve(values.root ?? process.cwd(), values.out ?? \"dist\"),\n        graph,\n        ...(values.url ? { deployedUrl: values.url } : {}),\n      });\n      report.diagnostics.unshift(...graph.diagnostics);\n      report.ok = !report.diagnostics.some((d) => d.severity === \"error\");\n      if (values.json) console.log(JSON.stringify(report, null, 2));\n      else {\n        if (report.diagnostics.length)\n          console.log(formatDiagnostics(report.diagnostics));\n        console.log(\n          `${report.ok ? \"Passed\" : \"Failed\"} ${report.scope} checks: ${report.pages} pages, ${report.assets} assets${report.checkedUrls ? `, ${report.checkedUrls} deployed URLs` : \"\"}.`,\n        );\n      }\n      if (!report.ok) process.exitCode = 1;\n    } else\n      await update(\n        project,\n        positionals.slice(1),\n        values.json,\n        values[\"dry-run\"],\n      );\n  }\n} catch (error) {\n  const message = error instanceof Error ? error.message : String(error);\n  const diagnostics: DocsDiagnostic[] =\n    error && typeof error === \"object\" && \"diagnostics\" in error\n      ? (error.diagnostics as DocsDiagnostic[])\n      : [{ code: \"COOKBOOK_CLI_ERROR\", severity: \"error\", message }];\n  if (jsonOutput) {\n    console.log(\n      JSON.stringify({ ok: false, pages: 0, assets: 0, diagnostics }, null, 2),\n    );\n  } else {\n    console.error(formatDiagnostics(diagnostics));\n  }\n  process.exitCode = 1;\n}\n\nasync function doctor(\n  project: DocsProject,\n  json: boolean,\n  publicDirectory?: string,\n): Promise<void> {\n  const theme = resolveDocsTheme(project.config.theme);\n  const graph = await createDocsGraph(project);\n  const diagnostics = [\n    ...graph.diagnostics,\n    ...theme.diagnostics,\n    ...(await validateProjectAssets(project, graph, publicDirectory)),\n  ];\n  const hasErrors = diagnostics.some(\n    (diagnostic) => diagnostic.severity === \"error\",\n  );\n  if (json) {\n    console.log(\n      JSON.stringify(\n        {\n          ok: !hasErrors,\n          scope: \"preflight\",\n          buildVerified: false,\n          pages: graph.entries.length,\n          assets: graph.assets.length,\n          diagnostics,\n        },\n        null,\n        2,\n      ),\n    );\n  } else if (diagnostics.length > 0) {\n    console.log(formatDiagnostics(diagnostics));\n  } else {\n    console.log(\n      `Preflight passed: ${graph.entries.length} pages, ${graph.assets.length} content assets. MDX compilation, remote fonts, and deployment are not checked. Run astro build and cookbook check-build.`,\n    );\n  }\n  if (hasErrors) process.exitCode = 1;\n}\n\nasync function update(\n  project: DocsProject,\n  packages: string[],\n  json: boolean,\n  dryRun: boolean,\n): Promise<void> {\n  const existing = await readDocsLock(project.root);\n  const next = await reconcileDocsLock(project.config, existing, { packages });\n  const changes = next.sources.map((source) => ({\n    requested: source.requested,\n    from:\n      existing?.sources.find(\n        (current) => current.requested === source.requested,\n      )?.resolved ?? null,\n    to: source.resolved,\n  }));\n  const removed =\n    existing?.sources\n      .filter(\n        (source) =>\n          !next.sources.some(\n            (current) => current.requested === source.requested,\n          ),\n      )\n      .map((source) => source.requested) ?? [];\n  if (!dryRun) {\n    const build = normalizeDocsConfig(project.config).build;\n    for (const source of next.sources) {\n      if (!source.vendored) continue;\n      const current = existing?.sources.find(\n        (entry) => entry.requested === source.requested,\n      );\n      if (\n        current?.vendored === source.vendored &&\n        current.integrity === source.integrity\n      )\n        continue;\n      const { vendored, ...remote } = source;\n      const artifact = await materializePackage(remote, build, project.root);\n      const destination = resolve(project.root, vendored);\n      await mkdir(dirname(destination), { recursive: true });\n      await cp(artifact, destination, { recursive: true });\n    }\n    await writeDocsLock(project.root, next);\n  }\n  if (json) {\n    console.log(\n      JSON.stringify(\n        {\n          ok: true,\n          pages: 0,\n          assets: 0,\n          diagnostics: [],\n          dryRun,\n          changes,\n          removed,\n          lock: next,\n        },\n        null,\n        2,\n      ),\n    );\n  } else {\n    for (const change of changes)\n      console.log(\n        `${change.requested}: ${change.from ?? \"(new)\"} -> ${change.to}`,\n      );\n    for (const source of removed) console.log(`Removed ${source}`);\n    console.log(\n      dryRun\n        ? \"Dry run: cookbook.lock.json is unchanged.\"\n        : \"Updated cookbook.lock.json.\",\n    );\n  }\n}\n\nfunction printHelp(): never {\n  console.log(\n    `Usage: cookbook <command> [options]\\n\\nCommands:\\n  doctor             Check configuration, content graph, theme, and local files\\n  check-build        Inspect production output and optionally deployed URLs\\n  update [packages]  Reconcile configured package sources and their lock\\n\\nOptions:\\n  --root <directory>\\n  --config <path>\\n  --public-dir <directory>  Local public assets for doctor (default: public)\\n  --out <directory>        Built output (default: dist)\\n  --url <base-url>         Also check a deployed site\\n  --dry-run          Preview an update without writing files\\n  --json\\n  -h, --help`,\n  );\n  process.exit(0);\n}\n"],"mappings":"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"}

package/dist/components.d.ts

@@ -1,4 +1,4 @@
 
-import { Callout, Card, CodeGroup, Logo, Preview, Steps, Tab, Tabs } from "@tenphi/starlight/components";
-export type * from "@tenphi/starlight/components";
+import { Callout, Card, CodeGroup, Logo, Preview, Steps, Tab, Tabs } from "@tenphi/renderer/components";
+export type * from "@tenphi/renderer/components";
 export { Callout, Card, CodeGroup, Logo, Preview, Steps, Tab, Tabs };

package/dist/components.js

@@ -1,3 +1,3 @@
 #!/usr/bin/env node
-import { Callout, Card, CodeGroup, Logo, Preview, Steps, Tab, Tabs } from "@tenphi/starlight/components";
+import { Callout, Card, CodeGroup, Logo, Preview, Steps, Tab, Tabs } from "@tenphi/renderer/components";
 export { Callout, Card, CodeGroup, Logo, Preview, Steps, Tab, Tabs };

package/dist/content.d.ts

@@ -1,3 +1,3 @@
 
-import { getCookbookCollection, getCookbookEntry } from "@tenphi/starlight/content";
+import { getCookbookCollection, getCookbookEntry } from "@tenphi/renderer/content";
 export { getCookbookCollection, getCookbookEntry };

package/dist/content.js

@@ -1,3 +1,3 @@
 #!/usr/bin/env node
-import { getCookbookCollection, getCookbookEntry } from "@tenphi/starlight/content";
+import { getCookbookCollection, getCookbookEntry } from "@tenphi/renderer/content";
 export { getCookbookCollection, getCookbookEntry };

package/dist/eslint-plugin.d.ts

@@ -1,3 +1,3 @@
 
-import eslint_plugin_default, { ResolvedConfig, StyleFunctionConfig, TastyValidationConfig, createValidationConfig, recommended, strict, validationConfig } from "@tenphi/starlight/eslint-plugin";
+import eslint_plugin_default, { ResolvedConfig, StyleFunctionConfig, TastyValidationConfig, createValidationConfig, recommended, strict, validationConfig } from "@tenphi/renderer/eslint-plugin";
 export { type ResolvedConfig, type StyleFunctionConfig, type TastyValidationConfig, createValidationConfig, eslint_plugin_default as default, recommended, strict, validationConfig };

package/dist/eslint-plugin.js

@@ -1,3 +1,3 @@
 #!/usr/bin/env node
-import eslint_plugin_default, { createValidationConfig, recommended, strict, validationConfig } from "@tenphi/starlight/eslint-plugin";
+import eslint_plugin_default, { createValidationConfig, recommended, strict, validationConfig } from "@tenphi/renderer/eslint-plugin";
 export { createValidationConfig, eslint_plugin_default as default, recommended, strict, validationConfig };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 
-import starlight_default, { CookbookOptions, DEFAULT_THEME_TOKENS, DEFAULT_TYPOGRAPHY_PRESETS } from "@tenphi/starlight";
+import renderer_default, { CookbookOptions, DEFAULT_THEME_TOKENS, DEFAULT_TYPOGRAPHY_PRESETS } from "@tenphi/renderer";
 import { BrandConfig, BrandDeclaration, BreadcrumbItem, BuildConfig, COOKBOOK_COMPONENT_NAMES, COOKBOOK_COMPONENT_SUB_ELEMENTS, COOKBOOK_PALETTE_NAMES, ComponentStyleConfig, ComponentStyles, ComponentStylesConfig, ComponentsConfig, ContentConfig, CookbookComponentName, CookbookComponentStyles, CookbookComponentSubElementName, DocsAsset, DocsConfig, DocsDiagnostic, DocsEntry, DocsFrontmatter, DocsGraph, DocsRoute, DocsSource, EditLinkConfig, FontLoadingConfig, HeadConfig, LocaleConfig, MarkdownConfig, NavigationConfig, NavigationItem, NavigationPlacement, NavigationTab, PageSeoConfig, SearchConfig, SiteConfig, SiteIconConfig, SiteLogoConfig, SiteSeoConfig, SiteVersion, SocialImage, TableOfContentsConfig, ThemeConfig, ThemeFont, ThemeFontFile, ThemeFonts, ThemePaletteColor, ThemePaletteConfig, ThemeTokenValue, ThemeTokens, TypographyPreset, TypographyPresets, defineDocsConfig, mergeDocsConfig } from "@tenphi/docs";
-export { type BrandConfig, type BrandDeclaration, type BreadcrumbItem, type BuildConfig, COOKBOOK_COMPONENT_NAMES, COOKBOOK_COMPONENT_SUB_ELEMENTS, COOKBOOK_PALETTE_NAMES, type ComponentStyleConfig, type ComponentStyles, type ComponentStylesConfig, type ComponentsConfig, type ContentConfig, type CookbookComponentName, type CookbookComponentStyles, type CookbookComponentSubElementName, type CookbookOptions, DEFAULT_THEME_TOKENS, DEFAULT_TYPOGRAPHY_PRESETS, type DocsAsset, type DocsConfig, type DocsDiagnostic, type DocsEntry, type DocsFrontmatter, type DocsGraph, type DocsRoute, type DocsSource, type EditLinkConfig, type FontLoadingConfig, type HeadConfig, type LocaleConfig, type MarkdownConfig, type NavigationConfig, type NavigationItem, type NavigationPlacement, type NavigationTab, type PageSeoConfig, type SearchConfig, type SiteConfig, type SiteIconConfig, type SiteLogoConfig, type SiteSeoConfig, type SiteVersion, type SocialImage, type TableOfContentsConfig, type ThemeConfig, type ThemeFont, type ThemeFontFile, type ThemeFonts, type ThemePaletteColor, type ThemePaletteConfig, type ThemeTokenValue, type ThemeTokens, type TypographyPreset, type TypographyPresets, starlight_default as default, defineDocsConfig, mergeDocsConfig };
+export { type BrandConfig, type BrandDeclaration, type BreadcrumbItem, type BuildConfig, COOKBOOK_COMPONENT_NAMES, COOKBOOK_COMPONENT_SUB_ELEMENTS, COOKBOOK_PALETTE_NAMES, type ComponentStyleConfig, type ComponentStyles, type ComponentStylesConfig, type ComponentsConfig, type ContentConfig, type CookbookComponentName, type CookbookComponentStyles, type CookbookComponentSubElementName, type CookbookOptions, DEFAULT_THEME_TOKENS, DEFAULT_TYPOGRAPHY_PRESETS, type DocsAsset, type DocsConfig, type DocsDiagnostic, type DocsEntry, type DocsFrontmatter, type DocsGraph, type DocsRoute, type DocsSource, type EditLinkConfig, type FontLoadingConfig, type HeadConfig, type LocaleConfig, type MarkdownConfig, type NavigationConfig, type NavigationItem, type NavigationPlacement, type NavigationTab, type PageSeoConfig, type SearchConfig, type SiteConfig, type SiteIconConfig, type SiteLogoConfig, type SiteSeoConfig, type SiteVersion, type SocialImage, type TableOfContentsConfig, type ThemeConfig, type ThemeFont, type ThemeFontFile, type ThemeFonts, type ThemePaletteColor, type ThemePaletteConfig, type ThemeTokenValue, type ThemeTokens, type TypographyPreset, type TypographyPresets, renderer_default as default, defineDocsConfig, mergeDocsConfig };

package/dist/index.js

@@ -1,4 +1,4 @@
 #!/usr/bin/env node
-import starlight_default, { DEFAULT_THEME_TOKENS, DEFAULT_TYPOGRAPHY_PRESETS } from "@tenphi/starlight";
+import renderer_default, { DEFAULT_THEME_TOKENS, DEFAULT_TYPOGRAPHY_PRESETS } from "@tenphi/renderer";
 import { COOKBOOK_COMPONENT_NAMES, COOKBOOK_COMPONENT_SUB_ELEMENTS, COOKBOOK_PALETTE_NAMES, defineDocsConfig, mergeDocsConfig } from "@tenphi/docs";
-export { COOKBOOK_COMPONENT_NAMES, COOKBOOK_COMPONENT_SUB_ELEMENTS, COOKBOOK_PALETTE_NAMES, DEFAULT_THEME_TOKENS, DEFAULT_TYPOGRAPHY_PRESETS, starlight_default as default, defineDocsConfig, mergeDocsConfig };
+export { COOKBOOK_COMPONENT_NAMES, COOKBOOK_COMPONENT_SUB_ELEMENTS, COOKBOOK_PALETTE_NAMES, DEFAULT_THEME_TOKENS, DEFAULT_TYPOGRAPHY_PRESETS, renderer_default as default, defineDocsConfig, mergeDocsConfig };

package/dist/styling.d.ts

@@ -1,3 +1,3 @@
 
-import { Styles, defineComponent, mergeStyles, resolveComponentStyles, tasty, useGlobalStyles } from "@tenphi/starlight/styling";
+import { Styles, defineComponent, mergeStyles, resolveComponentStyles, tasty, useGlobalStyles } from "@tenphi/renderer/styling";
 export { type Styles, defineComponent, mergeStyles, resolveComponentStyles, tasty, useGlobalStyles };

package/dist/styling.js

@@ -1,3 +1,3 @@
 #!/usr/bin/env node
-import { defineComponent, mergeStyles, resolveComponentStyles, tasty, useGlobalStyles } from "@tenphi/starlight/styling";
+import { defineComponent, mergeStyles, resolveComponentStyles, tasty, useGlobalStyles } from "@tenphi/renderer/styling";
 export { defineComponent, mergeStyles, resolveComponentStyles, tasty, useGlobalStyles };

package/docs/architecture.md

@@ -8,17 +8,21 @@ sidebar:
 Cookbook keeps content concerns separate from rendering so another renderer
 can consume the same validated graph in the future.
 
+Cookbook's early documentation experience was inspired by
+[Astro Starlight](https://starlight.astro.build/). Its current renderer is
+maintained in this repository.
+
 ## Packages
 
-| Package                   | Responsibility                                                                                              |
-| ------------------------- | ----------------------------------------------------------------------------------------------------------- |
-| `@tenphi/create-cookbook` | Inspect an npm artifact and scaffold a reproducible documentation project                                   |
-| `@tenphi/cookbook`        | Provide the memorable Astro integration, public config exports, and CLI                                     |
-| `@tenphi/docs`            | Discover sources, resolve packages, build the content graph, transform Markdown, and report diagnostics     |
-| `@tenphi/starlight`       | Adapt the graph to Astro/Starlight and provide the Tasty/Glaze theme, components, search, and static assets |
+| Package                   | Responsibility                                                                                          |
+| ------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `@tenphi/create-cookbook` | Inspect an npm artifact and scaffold a reproducible documentation project                               |
+| `@tenphi/cookbook`        | Provide the memorable Astro integration, public config exports, and CLI                                 |
+| `@tenphi/docs`            | Discover sources, resolve packages, build the content graph, transform Markdown, and report diagnostics |
+| `@tenphi/renderer`        | Render the graph with Astro and provide the Tasty/Glaze theme, components, search, and static assets    |
 
 The `@tenphi/cookbook` default export represents the complete product. Consumers do
-not compose Starlight or renderer internals themselves.
+not compose renderer internals themselves.
 
 ## Build pipeline
 
@@ -28,7 +32,7 @@ not compose Starlight or renderer internals themselves.
 4. Parse Markdown and collect headings, links, and assets.
 5. Rewrite internal references through the completed route graph.
 6. Reject unsafe paths and report strict diagnostics.
-7. Render static pages through Astro and Starlight.
+7. Render static pages through Astro and Cookbook components.
 8. Copy content-hashed assets and build the local Pagefind index.
 
 Source documents are read-only throughout this process. The transformed body
@@ -44,7 +48,7 @@ Theme resolution has three deliberately separate layers:
 2. The Glaze values, design tokens, typography presets, states, and units are
    registered directly with Tasty.
 3. Cookbook components use `tasty()` and the Tasty selector bridge styles DOM
-   owned by Astro, Starlight, Expressive Code, Pagefind, and rendered Markdown.
+   owned by Astro, Pagefind, and rendered Markdown.
 
 The palette owns color relationships. Components never choose raw light/dark
 colors, and shape tokens never contain palette logic. This keeps a palette
@@ -78,7 +82,7 @@ for (const route of graph.routes) {
 ```
 
 The graph exposes normalized entries, routes, assets, and structured
-diagnostics without importing Starlight.
+diagnostics without importing the renderer.
 
 ## Reference app
 

package/docs/comparison.md

@@ -0,0 +1,129 @@
+---
+title: Compare documentation tools
+description: Choose between Cookbook, documentation site builders, hosted docs, and generated API or component references.
+sidebar:
+  order: 2
+---
+
+Two choices shape a documentation site: **how closely it should follow your
+product's design system** and **where its content comes from**. Cookbook was
+built for both. Its theme is configurable down to named component parts, and
+its content can come from existing repository files or a published npm package.
+Turning Markdown into pages is only one part of that workflow.
+
+The comparisons below describe each tool's documented starting workflow, not
+every integration its users could build. They are a selection of established
+options, not a popularity ranking or an exhaustive list.
+
+## Why choose Cookbook for customization?
+
+Cookbook treats appearance as a supported configuration surface rather than a
+set of selectors to override after rendering:
+
+- Set one `theme.brand` color or define semantic `theme.palette` roles. Glaze
+  resolves them for light, dark, normal, and high-contrast modes, with contrast
+  targets and diagnostics.
+- Configure shared `theme.tokens`, font roles, typography `theme.presets`, and
+  responsive `theme.states` once. Components consume those roles consistently.
+- Change a built-in component through a **partial**
+  `theme.styles.<ComponentName>` Tasty object. Cookbook merges it into the full
+  base style before extracting CSS. Its [named component parts](./theme-and-components.md#style-customization)
+  are published so a header title, search field, or sidebar item can be changed
+  without copying an entire component.
+- Add a styled component with `defineComponent()` or replace markup and behavior
+  through an Astro component override when the supported anatomy is not enough.
+  Tasty and Glaze run during the build; the browser receives static CSS, not
+  their styling runtimes.
+
+For example, this changes the brand, a shared radius, heading typography, and
+one part of the header while keeping the other default component styles:
+
+```ts
+import { defineDocsConfig } from "@tenphi/cookbook/config";
+
+export default defineDocsConfig({
+  theme: {
+    brand: { from: "#315efb" },
+    tokens: { $radius: "10px" },
+    presets: { heading: { fontWeight: 650 } },
+    styles: { Header: { SiteTitle: { preset: "h4 / strong" } } },
+  },
+});
+```
+
+This style contract is specific to Cookbook's Tasty and Glaze system. Structural
+changes still require an Astro override. Read the [customization rules](./customization-rules.md)
+and [theme reference](./theme-and-components.md) for the supported names and
+the full design-system API.
+
+## Start with the material you have
+
+- **A repository `README.md` and `docs/` tree:** Start with
+  [Cookbook](./getting-started.md), [Starlight](https://starlight.astro.build/getting-started/),
+  [VitePress](https://vitepress.dev/guide/getting-started), or another site
+  builder. Choose the framework and editing workflow you prefer; Cookbook can
+  read the existing files in place.
+- **Markdown inside a published npm package:**
+  [Cookbook's package source](./content-sources.md#npm-package-sources) reads
+  the published artifact, pins its version and integrity, and builds without
+  installing that package.
+- **TypeScript exports and code comments:** [TypeDoc](https://typedoc.org/index.html)
+  generates reference pages from the code model and can use package entry
+  points.
+- **UI components and their stories:** [Storybook Autodocs](https://storybook.js.org/docs/writing-docs)
+  documents components alongside rendered stories.
+- **An OpenAPI specification:** Choose [Cookbook's static reference](./content-sources.md#openapi-references)
+  or a tool with an [interactive API playground](https://mintlify.com/docs/api-playground/overview)
+  if readers need to make requests from the docs.
+
+## Compare complete documentation sites
+
+All of these tools support visual customization. Their default content and
+styling contracts differ:
+
+| Tool and usual source                                                                                                                                  | Documented customization path                                                                                                                                                                                 |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Cookbook** — Astro site reading repository paths, locked npm artifacts, or local OpenAPI.                                                            | Semantic Glaze palette, Tasty tokens and presets, partial named component styles, and Astro overrides; extracted static CSS.                                                                                  |
+| [**Starlight**](https://starlight.astro.build/guides/pages/) — Astro docs collection with [plugins](https://starlight.astro.build/reference/plugins/). | [CSS variables, custom CSS or Tailwind](https://starlight.astro.build/guides/css-and-tailwind/), themes, and component overrides.                                                                             |
+| [**Docusaurus**](https://docusaurus.io/docs/docs-introduction) — React/MDX docs with [version snapshots](https://docusaurus.io/docs/versioning).       | [Infima variables and custom CSS](https://docusaurus.io/docs/styling-layout), plus [swizzled React components](https://docusaurus.io/docs/swizzling).                                                         |
+| [**VitePress**](https://vitepress.dev/guide/what-is-vitepress) — Markdown site with Vue components.                                                    | [Theme config, CSS variables, Vue layout slots, or a custom theme](https://vitepress.dev/guide/extending-default-theme).                                                                                      |
+| [**Nextra**](https://nextra.site/docs) — Next.js/React site with Markdown and MDX.                                                                     | [Next.js CSS](https://nextra.site/docs/guide/custom-css) or a [custom React theme](https://nextra.site/docs/custom-theme).                                                                                    |
+| [**Material for MkDocs**](https://squidfunk.github.io/mkdocs-material/getting-started/) — Python/MkDocs site with Markdown.                            | [Palette settings and CSS variables](https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/), [extra CSS and template overrides](https://squidfunk.github.io/mkdocs-material/customization/). |
+| [**Mintlify**](https://mintlify.com/docs/quickstart) — Managed MDX and OpenAPI site with Git-connected deployment and a web editor.                    | [Prebuilt themes](https://mintlify.com/docs/themes), configuration for colors and fonts, and visual editing.                                                                                                  |
+
+The table compares documented approaches, not a ceiling on what each tool can
+do. Choose the styling model you want to maintain. Cookbook's model is useful
+when brand, typography, semantic colors, and component anatomy must move
+together across the whole site. Starlight, Docusaurus, VitePress, Nextra, and
+Material for MkDocs provide their own routes to theme or component changes;
+Mintlify provides a managed editing and hosting workflow. Cookbook requires an
+Astro build and a host for its static output. Starlight plugins target its own
+APIs and do not run in Cookbook; see [Cookbook extensions](./plugins.md).
+
+## When the package _is_ the source
+
+“Package to website” can mean two different jobs:
+
+1. **Publish the prose included in an npm release.** Cookbook reads the actual
+   tarball's selected `README.md` and Markdown files. Package MDX requires an
+   explicit trust opt-in before its code can run. `cookbook update`
+   records the requested specifier, resolved version, and integrity in
+   `cookbook.lock.json`; a production build uses that lock. This is useful when
+   the docs site should describe exactly what package consumers received. See
+   [package sources](./content-sources.md#npm-package-sources) and the
+   [package quick start](./getting-started.md#document-a-published-npm-package).
+2. **Generate reference pages from source code.** [TypeDoc](https://typedoc.org/index.html)
+   reads TypeScript exports and comments, including entry points discovered
+   from `package.json`, and emits an HTML or JSON reference. It is the direct
+   choice when exported types and signatures are the documentation.
+
+For a component library, [Storybook](https://storybook.js.org/docs/writing-docs)
+is a separate option when the main experience should be runnable component
+examples. TypeDoc or Storybook can complement a guide site; link to their output
+from Cookbook navigation when each serves a different reader need.
+
+Cookbook does not extract API signatures from TypeScript or provide an
+interactive OpenAPI client. Its strengths are design system customization,
+source-aware prose, validated links and assets, and a reproducible npm artifact
+input. See [content sources](./content-sources.md) and
+[theme and components](./theme-and-components.md) for the supported scope.

package/docs/configuration.md

@@ -185,13 +185,10 @@ path, not a generated content-collection path. Set `editUrl: false` or
 sources show a timestamp only when their materialized file has Git history or
 the page supplies one explicitly.
 
-These settings intentionally mirror Starlight's
-[`editLink`](https://starlight.astro.build/reference/configuration/#editlink)
-and
-[`lastUpdated`](https://starlight.astro.build/reference/configuration/#lastupdated)
-configuration while preserving Cookbook's original source paths.
+These settings use Cookbook's original source paths when constructing links and
+timestamps.
 
-Cookbook also accepts Starlight-compatible page presentation frontmatter:
+Cookbook also accepts page presentation frontmatter:
 
 ```yaml
 tableOfContents:
@@ -227,7 +224,7 @@ discoverable on the next build. A draft URL is public; this is not access contro
 
 ## Languages
 
-Expose Starlight's multilingual routing and language picker directly:
+Configure Cookbook's multilingual routing and language picker:
 
 ```ts
 locales: {
@@ -483,19 +480,9 @@ Configure renderer-level Markdown options such as custom remark or rehype
 plugins and Shiki languages through Astro's top-level `markdown` configuration.
 Cookbook preserves those settings while adding its own build-time transforms.
 
-Starlight content and behavior plugins can be supplied to the Astro integration:
-
-```ts
-import myStarlightPlugin from "./plugins/my-starlight-plugin.js";
-
-export default defineConfig({
-  integrations: [cookbook({ plugins: [myStarlightPlugin()] })],
-});
-```
-
-Cookbook preserves custom metadata for route middleware and supports custom schemas.
-See the [plugin compatibility guide](./plugins.md) for the tested ecosystem matrix,
-content query API, Tasty adapters, and collection/style limitations.
+Cookbook preserves custom metadata and supports custom schemas. See
+[extending Cookbook](./plugins.md) for Astro Markdown plugins, native GitHub
+alerts, the content query API, and styling limits.
 
 Cookbook renders fenced `mermaid` blocks as responsive, theme-aware SVG during
 the static build. Flowcharts, state, sequence, class, and entity-relationship
@@ -624,8 +611,7 @@ a 120ms slide transition; customize these through `theme.styles.Sidebar`.
 ### Translate Cookbook controls
 
 Cookbook includes English and French interface messages. Other languages use
-English for missing Cookbook messages while Starlight supplies its own built-in
-translations. Override messages by language code; regional codes fall back to the
+English for missing messages. Override messages by language code; regional codes fall back to the
 base language and then English:
 
 ```ts

package/docs/content-sources.md

@@ -170,7 +170,7 @@ Package Markdown is untrusted by default. Raw HTML is sanitized to safe
 elements, HTML-capable frontmatter is stripped, custom `head` entries are discarded,
 unsafe URL protocols are rejected, and MDX cannot execute. Set `trust: "mdx"`
 only after reviewing the exact locked artifact; doing so allows its build-time
-code to run. Trusted MDX is compiled by Starlight, including relative component
+code to run. Trusted MDX is compiled by Astro, including relative component
 imports from the source file's directory. Package-provided indexes, include
 patterns, exclude patterns, and every discovered file are confined to the
 extracted artifact root.

package/docs/customization-rules.md

@@ -45,7 +45,7 @@ import { defineDocsConfig } from "@tenphi/cookbook/config";
 export default defineDocsConfig({
   theme: {
     styles: {
-      StarlightHeader: { SiteTitle: { preset: "h4 / strong" } },
+      Header: { SiteTitle: { preset: "h4 / strong" } },
     },
   },
 });
@@ -68,7 +68,7 @@ integration or calling upstream `configure()` is unnecessary. Shared settings
 belong in `docs.config.ts`.
 
 * Express styles with Tasty. Do not add CSS files, CSS modules, Astro `<style>`
-  blocks, inline `style` attributes, or imported Starlight styles to customize
+  blocks, inline `style` attributes, or imported component styles to customize
   the documentation interface. The isolated content of `Preview` is a separate
   demonstration surface.
 * Model descendants and pseudo-elements as named sub-elements inside the

package/docs/getting-started.md

@@ -67,7 +67,7 @@ import cookbook from "@tenphi/cookbook";
 export default defineConfig({ integrations: [cookbook()] });
 ```
 
-Cookbook includes Starlight and discovers `docs.config.ts` automatically.
+Cookbook includes its Astro renderer and discovers `docs.config.ts` automatically.
 With no documentation configuration, it uses README/docs conventions.
 
 ## Configure the site

package/docs/index.md

@@ -1,18 +1,18 @@
 ---
 title: Cookbook
-description: Build a polished static documentation site from the Markdown your project already owns.
+description: Build a customizable static documentation site from the Markdown your project already owns.
 template: splash
 hero:
   title: Documentation that stays with the code.
-  tagline: Turn repository Markdown or a locked npm package into a polished, searchable Astro site—without creating a second source of truth.
+  tagline: Turn repository Markdown or a locked npm package into an Astro docs site that fits your design system—without creating a second source of truth.
   image:
     html: '<svg xmlns="http://www.w3.org/2000/svg" width="240" height="240" viewBox="0 0 64 64" aria-hidden="true"><rect width="64" height="64" rx="14" fill="currentColor"/><path fill="#fff" d="M14.8 16c6.7.2 12.3 2 16.7 5.4v28.4c-4.4-3.1-10-4.7-16.6-4.9a3 3 0 0 1-2.9-3V19a3 3 0 0 1 2.8-3Z"/><path fill="#fff" d="M49.2 16c-6.7.2-12.3 2-16.7 5.4v28.4c4.4-3.1 10-4.7 16.6-4.9a3 3 0 0 0 2.9-3V19a3 3 0 0 0-2.8-3Z"/></svg>'
   actions:
     - text: Get started
       link: /getting-started/
       variant: primary
-    - text: See how it compares
-      link: /starlight-comparison/
+    - text: Compare tools
+      link: /comparison/
       variant: secondary
 sidebar:
   order: 1
@@ -20,7 +20,7 @@ sidebar:
 ## Keep documentation close to its source
 
 Cookbook combines [Astro](https://astro.build) and
-[Starlight](https://starlight.astro.build) with repository-aware content,
+an Astro renderer with repository-aware content,
 strict validation, local Pagefind search, and a theme powered by
 [Tasty](./upstream/tasty/README.md) and [Glaze](./upstream/glaze/README.md).
 
@@ -42,8 +42,8 @@ for GitHub Pages or any static host.
 
 ### Styling that fits your product
 
-Glaze turns a brand and semantic palette into light, dark, and high-contrast
-colors with contrast targets. Tasty applies those color roles alongside shared
+[Glaze](./upstream/glaze/README.md) turns a brand and semantic palette into light, dark, and high-contrast
+colors with contrast targets. [Tasty](./upstream/tasty/README.md) applies those color roles alongside shared
 tokens and typography presets, so the docs can follow your design system.
 State maps keep hover, focus, and responsive values beside the styles they
 change. Partial `theme.styles` overrides merge before CSS extraction, letting
@@ -57,11 +57,12 @@ states, and named component styles.
 | I want to…                           | Start here                              | Then read                                                             |
 | ------------------------------------ | --------------------------------------- | --------------------------------------------------------------------- |
 | Start a site                         | [Getting started](./getting-started.md) | [Validate and deploy](./deployment.md)                                |
+| Choose a documentation tool          | [Compare tools](./comparison.md)        | [Getting started](./getting-started.md)                               |
 | Have an agent set it up              | [AI agent workflow](./ai-agents.md)     | [Customization rules](./customization-rules.md)                       |
 | Bring existing Markdown or an API    | [Content sources](./content-sources.md) | [Working examples](./examples.md)                                     |
 | Write pages and interactive examples | [Authoring](./authoring.mdx)            | [Mobile contents and hero images](./authoring.mdx#on-page-navigation) |
 | Change brand, fonts, or logo         | [Configuration recipes](./recipes.md)   | [Theme reference](./theme-and-components.md)                          |
-| Add a Starlight plugin               | [Plugin compatibility](./plugins.md)    | [Architecture](./architecture.md)                                     |
+| Add a Markdown extension             | [Extend Cookbook](./plugins.md)         | [Architecture](./architecture.md)                                     |
 | Publish for people and agents        | [Deployment](./deployment.md)           | [Publishing metadata](./publishing.md)                                |
 | Update or fix an existing site       | [Upgrade Cookbook](./migration.md)      | [Troubleshooting](./troubleshooting.md)                               |
 

package/docs/migration.md

@@ -38,9 +38,40 @@ upgrade the site's Cookbook runtime or package-manager dependencies. Commit the
 documentation lock separately when intentionally updating imported content.
 Local Markdown needs no lock update.
 
+## 0.18.x to 0.19
+
+Cookbook now renders documentation with its own Astro components. The public
+`@tenphi/cookbook` integration remains the normal entry point. Projects that
+import the renderer package directly should replace `@tenphi/starlight` with
+`@tenphi/renderer`.
+
+The page and theme contracts remain familiar, but component overrides now read
+`Astro.locals.cookbookRoute`. Replace uses of `Astro.locals.starlightRoute` in
+your own overrides. The named style surfaces `StarlightHeader` and
+`StarlightAside` become `Header` and `MarkdownAlert`; the unused Starlight card,
+link-card, badge, and steps bridges are removed. Cookbook's `Card`, `Callout`,
+and `Steps` components remain available.
+
+Renderer class names now use Cookbook-owned names. Update any custom CSS or
+scripts that target generated markup, and prefer the named `theme.styles`
+surfaces in the [theme reference](./theme-and-components.md).
+
+The `plugins` integration option no longer forwards Starlight hooks. Move
+content transforms to Astro's `markdown` configuration and use
+`frontmatterSchema` for custom page metadata. GitHub alert blockquotes render
+directly in Markdown and MDX, so `starlight-github-alerts` is no longer needed.
+Use `cookbook doctor` and `cookbook check-build` instead of plugins that inspect
+Starlight's content collection or physical docs files. See
+[extending Cookbook](./plugins.md) for examples.
+
+Build and preview each site after updating its package manifest. Check custom
+component overrides, locale navigation, search, and Tasty style names before
+deploying. Cookbook-saved appearance choices remain. Older Starlight-only
+choices are ignored; visitors who relied on one can select their scheme again.
+
 ## 0.17.x to 0.18
 
-These changes are included in the next minor release:
+These changes were introduced in 0.18:
 
 - **Google fonts:** family-name shorthand loads preset weights and italics and
   self-hosts the files. The initial build requires network access. Preserve the
@@ -63,7 +94,7 @@ These changes are included in the next minor release:
 - **Plugins:** custom metadata is available to route middleware and through
   Cookbook's content API. Plugins that need Astro's synthetic content files or
   inject their own CSS require adaptation. See the tested
-  [plugin matrix](./plugins.md#verified-compatibility).
+  [extension guide](./plugins.md).
 - **Styles:** rendered inline styles are rejected. Move custom styling to Tasty
   and registered theme style trees. Keep these components server-rendered;
   browser scripts and `client:*` islands cannot import Cookbook styling, Tasty,

package/docs/plugins.md

@@ -1,120 +1,99 @@
 ---
-title: Starlight plugins
+title: Extend Cookbook
+description: Add Markdown transforms, validate custom metadata, and query the content graph.
+sidebar:
+  order: 7
 ---
 
-Cookbook accepts Starlight content and behavior plugins in `astro.config.mjs`:
+Cookbook renders with Astro and accepts Astro Markdown integrations. Configure
+remark and rehype plugins in `astro.config.ts`; Cookbook adds its own transforms
+to the same processor. Extensions that emit CSS must be adapted to Tasty because
+the finished site ships only Tasty-generated styles.
 
-```js cookbook-verify=github-alerts
-import cookbook from "@tenphi/cookbook";
-import githubAlerts from "starlight-github-alerts";
+```ts
+import { defineConfig } from "astro/config";
 import { unified } from "@astrojs/markdown-remark";
+import cookbook from "@tenphi/cookbook";
+import myRemarkPlugin from "./plugins/my-remark-plugin.js";
 
-export default {
-  markdown: { processor: unified() },
-  integrations: [cookbook({ plugins: [githubAlerts()] })],
-};
+export default defineConfig({
+  markdown: { processor: unified({ remarkPlugins: [myRemarkPlugin] }) },
+  integrations: [cookbook()],
+});
 ```
 
-Install `starlight-github-alerts` and `@astrojs/markdown-remark` in your project. Cookbook supplies the Starlight runtime; respect
-plugins' peer dependency ranges when upgrading. See [configuration](./configuration.md)
-for Astro Markdown hooks and [customization](./theme-and-components.md) for styling.
+## GitHub alerts
 
-## Verified compatibility
+Cookbook renders GitHub alert blockquotes in Markdown and MDX without an extra
+plugin. `NOTE`, `TIP`, `IMPORTANT`, `WARNING`, and `CAUTION` map to the semantic
+note, tip, caution, and danger surfaces. For example:
 
-The consumer check `pnpm check:plugins` tests these versions with the repository's
-pinned Astro and Starlight versions. Compatibility with other versions is not implied.
+The default Astro integration is sufficient for alert rendering:
 
-| Integration                                                        | Tested version   | Contract                                                                                                                             |
-| ------------------------------------------------------------------ | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
-| `starlight-github-alerts`                                          | 0.4.0            | With `unified()`, Markdown and MDX alert syntax uses Cookbook's Tasty `StarlightAside` adapter.                                      |
-| `starlight-links-validator`                                        | 0.26.0           | Incompatible with mounted sources: error reporting assumes physical `src/content/docs` files. Cookbook rejects it with a diagnostic. |
-| Route middleware and `i18n:setup`                                  | Starlight 0.42.4 | Custom metadata, body, file path, and translations survive in real consumer builds with locales and a base path.                     |
-| Plugins requiring `astro:content`'s `docs` collection              | —                | Cookbook's renderer uses its own graph. Adapt to the content API below; no native collection is populated automatically.             |
-| Plugins supplying CSS, styled Astro components, or Expressive Code | —                | Require an adapter built with Tasty. The build rejects incompatible output.                                                          |
-
-GitHub Alerts 0.4.0 assumes an older Sätteri plugin structure and silently skips
-alerts with Starlight 0.42.4's default processor. Cookbook rejects that combination
-with a configuration hint. Use `unified()` as above, or Starlight's native
-`:::note` / `:::tip` directives with the default processor.
+```js cookbook-verify=github-alerts
+import cookbook from "@tenphi/cookbook";
 
-GitHub alerts inherit the semantic blue, green, yellow, and red surfaces. Customize
-`theme.styles.StarlightAside` with `Note`, `Tip`, `Caution`, `Danger`, `Title`, `Icon`,
-and `FirstContent`. Styles merge into the full owned tree; the plugin's stylesheet
-is unnecessary. All supported appearance modes use the Glaze palette.
+export default { integrations: [cookbook()] };
+```
 
-Cookbook validates graph links itself. `starlight-links-validator` 0.26.0 loads,
-but fails while reporting broken links because it tries to read synthesized
-`src/content/docs` paths. Its middleware also cannot add previously absent links
-to its validation store. Use Cookbook's doctor and built-output checks for mounted
-sources. Plugins that depend on native collection IDs or mutate routing after
-graph creation need a Cookbook-specific adapter.
+Write the alert in a Markdown or MDX page:
 
-## Custom metadata and schemas
+```md
+> [!TIP]
+> Keep source documentation next to the code it describes.
+```
 
-Unknown source frontmatter is preserved as `entry.metadata` by default, and is
-available to route middleware as `locals.starlightRoute.entry.data`. Cookbook's
-validated built-in fields take precedence. Set `content.frontmatter: "reject"`
-only if your site does not use custom metadata.
+Customize the result through `theme.styles.MarkdownAlert`. Its named
+sub-elements are `Note`, `Tip`, `Caution`, `Danger`, `Title`, and
+`FirstContent`.
 
-Optionally validate custom fields or supply defaults with a Zod-compatible schema:
+## Custom frontmatter
 
-```js
-import cookbook from "@tenphi/cookbook";
-import { z } from "astro/zod";
+Unknown frontmatter fields can be preserved as JSON metadata. Set
+`content.frontmatter: "preserve"`, then validate or add custom fields with
+`frontmatterSchema`:
 
-export default {
+```ts
+export default defineConfig({
   integrations: [
     cookbook({
-      frontmatterSchema: z.object({
-        owner: z.string().default("docs-team"),
-      }),
+      frontmatterSchema: {
+        parse(metadata) {
+          return { ...metadata, owner: metadata.owner ?? "maintainers" };
+        },
+      },
     }),
   ],
-};
+});
 ```
 
-The schema receives **custom metadata only** and may use `parse` or `parseAsync`.
-Returned fields merge with preserved metadata. Values must be JSON-compatible;
-errors identify the source file. Reserved fields such as `title`, `slug`, `draft`,
-and `aliases` belong in source frontmatter and cannot be set by this schema.
-A schema cannot change routing or discovery after the graph is built.
+The schema receives only custom metadata. It cannot change route, title, draft,
+or other reserved page fields. Returned values must be JSON-safe because the
+renderer passes them through a build-time virtual module.
 
-Route middleware also receives the transformed Markdown source in `entry.body`
-and the actual source location in `entry.filePath`. Presentation changes made by
-middleware do not update the graph, sitemap, or agent text. Put shared publishing
-metadata in source configuration so every output agrees.
+## Read the content graph
 
-## Query Cookbook content
+Server-rendered Astro components can query the validated graph:
 
-Use this build-time API in Astro components and route middleware:
-
-```js
+```ts
 import {
   getCookbookCollection,
   getCookbookEntry,
 } from "@tenphi/cookbook/content";
 
-const pages = getCookbookCollection();
-const allPages = getCookbookCollection({ includeDrafts: true });
-const page = getCookbookEntry("/guide");
+const visiblePages = getCookbookCollection();
+const guide = getCookbookEntry("/guide");
 ```
 
-The renderer package exposes the same functions at `@tenphi/starlight/content`.
-Routes include locale/version prefixes but exclude Astro's deployment `base`.
-Collection queries omit drafts by default; exact lookups can retrieve a draft.
-Results are independent snapshots, including `metadata`, `frontmatter`, `body`,
-`transformedBody`, source information, headings, and links. Mutating a result does
-not change generated pages. Do not import this API into client-side code: it is
-backed by the site's build-time content graph.
-
-## Diagnose incompatible plugins
-
-- **Plugin adds `customCss`:** disable its stylesheet option and provide a Tasty
-  adapter, or choose a content-only plugin. The configuration error names the plugin.
-- **Inline styles or external stylesheet in built output:** replace that visual
-  component with owned markup styled through `tasty()` and registered
-  `theme.styles` anatomy. See [customization rules](./customization-rules.md).
-- **Empty `getCollection("docs")`:** use the Cookbook content API above. Cookbook
-  does not create a second, potentially conflicting Starlight content collection.
-- **Missing custom field:** keep `content.frontmatter` at its default `"preserve"`,
-  validate its shape, and read it after the Cookbook route bridge has run.
+Queries return snapshots. Drafts are omitted from the collection by default;
+`getCookbookEntry()` can retrieve one by its exact route. The same API is
+available at `@tenphi/renderer/content` for renderer-only projects.
+
+Component overrides receive page data from `Astro.locals.cookbookRoute`,
+including the current entry, locale, navigation, table of contents, and head
+tags. See [theme and components](./theme-and-components.md) for Tasty styling
+and [configuration](./configuration.md) for structural overrides.
+
+Use Astro's Markdown plugin APIs for content transforms, and Cookbook's graph
+and built-output checks for link validation. Extensions tied to another
+renderer need an adapter built against Cookbook's APIs.

package/docs/theme-and-components.md

@@ -125,13 +125,13 @@ Cookbook keeps literal surface seeds desaturated in the dark scheme so a nearly
 white tint does not become vivid dark chrome when its tone is inverted.
 
 Components consume semantic colors consistently: `surface`, `header`, `surface-2`,
-`surface-3`, `text`, `heading`, `text-soft`, `border`, `border-strong`, `accent-text`,
+`surface-3`, `text`, `heading`, `text-soft`, `sidebar-text`, `border`, `border-strong`, `accent-text`,
 `accent-surface`, `accent-surface-text`, `logo-surface`, `logo-mark`, and `focus`.
 Tasty components can use these as `#surface`, `#text`, `#border`, and so on; the Astro shell consumes the
 same resolved values. Glaze also generates hover and pressed states, subtle
 accent fills, overlays, shadows, and the orange, green, blue, purple, and red
-roles used by Starlight content components. No browser color mixes or
-Starlight fallback palette values participate in the rendered theme. Surface
+roles used by Cookbook content components. No browser color mixes or
+upstream fallback palette values participate in the rendered theme. Surface
 elevation uses Glaze's contrast-uniform tone axis: `surface-2` advances two tone
 steps and `surface-3` advances four from the base surface, with proportionally
 wider steps in high-contrast mode. Their saturation also steps down to 75% and
@@ -145,7 +145,7 @@ change border tone, not that restrained saturation relationship.
 The Appearance button in the desktop and mobile header opens one panel with
 Color scheme and Contrast sections. Color scheme offers Light, Dark, and Auto;
 Contrast offers Normal, High, and Auto. Each preference is independent, and
-existing saved choices are preserved. The panel supports keyboard navigation,
+selections are saved in the browser. The panel supports keyboard navigation,
 Escape, and outside-click dismissal. The popover fades and scales vertically
 from 96% to 100% over 120ms using native entry and exit transitions. Reduced
 motion disables the transition. Customize these states with
@@ -159,9 +159,14 @@ Interactive controls step up exactly one surface level: a control on `surface`
 uses `surface-2`, while a control on `surface-2` uses `surface-3`. Hover and
 pressed states build on that elevated surface without changing the border.
 Inputs stay on their surrounding surface so their border remains the visual
-boundary. Selected navigation uses the fixed-mode `accent-surface` and its
-paired `accent-surface-text`, so the brand fill does not drift toward the
-adaptive link color in dark mode.
+boundary. Primary buttons and selected navigation use the fixed-mode
+`accent-surface` and its paired light `accent-surface-text`. The brand fill
+keeps its polarity in dark mode while Glaze adjusts it to preserve label
+contrast.
+
+Page navigation keeps Next first in the keyboard order. It appears above
+Previous on narrow screens; wider layouts show Previous at the start and Next
+at the end.
 
 ## Design tokens
 
@@ -326,6 +331,10 @@ headings use a medium `610` weight and progressively gentle negative tracking.
 The separate `720` heading bold weight keeps emphasized heading text distinct.
 Navigation uses a lighter `450` weight with `580` for the current sidebar page,
 while smaller group labels establish hierarchy without oversized bold text.
+Inactive sidebar links use `sidebar-text`, a slightly softer blend of `text-soft`
+and the surface. In high-contrast mode it matches `text-soft`. Set
+`theme.palette['sidebar-text']` to adjust that color without changing other
+secondary text, or `theme.styles.Sidebar.Control` to customize the control.
 Top-level sidebar groups are always-visible section headings with their direct
 links aligned beneath them. Deeper groups expand on click or keyboard activation;
 the current group and its ancestors start open. Groups can have a parent-page
@@ -352,10 +361,9 @@ are useful when building a theme editor or presenting a reset action.
 ## Style customization
 
 Cookbook-owned interface elements are direct `tasty()` components. Supported
-Starlight-rendered surfaces use the same Tasty style trees through the global
-bridge. Customize either kind by name under `theme.styles`; the configuration
-is resolved before CSS generation, so this is not a selector-based CSS
-override.
+Cookbook components and generated Markdown surfaces use Tasty style trees.
+Customize them by name under `theme.styles`; the configuration is resolved
+before CSS generation, so this is not a selector-based CSS override.
 
 > **Direct styles, without a specificity battle.** Cookbook merges your partial
 > style object with the component's base styles before Tasty extracts CSS. The
@@ -368,13 +376,13 @@ below to find its exact anatomy:
 
 | Page area                     | Style names to inspect                                                               |
 | ----------------------------- | ------------------------------------------------------------------------------------ |
-| Header, title, and navigation | `HeaderFrame`, `StarlightHeader`, `SiteLogo`, `HeaderLinks`, `TopNavigation`         |
+| Header, title, and navigation | `HeaderFrame`, `Header`, `SiteLogo`, `HeaderLinks`, `TopNavigation`                  |
 | Sidebar and mobile menu       | `Sidebar`, `MobileMenuToggle`, `MobileNavigationTabs`, `MobileMenuFooter`            |
 | Article text and headings     | `Markdown`, `MarkdownHeading`, `Heading`, `MainContent`                              |
 | Code and diagrams             | `MarkdownCodeBlock`, `MarkdownInlineCode`, `SyntaxHighlight`, `CodeGroup`, `Mermaid` |
 | Search                        | `SearchButton`, `Search`, `SearchResults`                                            |
 | Table of contents             | `TableOfContents`, `MobileTableOfContents`, `TableOfContentsLayout`                  |
-| Cards, notes, and tabs        | `Card`, `StarlightCard`, `StarlightAside`, `Tabs`                                    |
+| Cards, notes, and tabs        | `Card`, `Callout`, `MarkdownAlert`, `Tabs`                                           |
 | Footer and page controls      | `Footer`, `Pagination`, `PageActions`, `ThemeSelect`                                 |
 
 For example, this changes a typography role and one named element without
@@ -455,7 +463,7 @@ sub-elements:
 | `MobileTableOfContents` | `Summary`, `List`, `NestedList`, `Item`, `Link`, `HoverLink`, `Focus`                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 | `PageActions`           | `Control`, `Hover`, `Focus`, `Pending`, `Status`                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | `Footer`                | `Meta`, `LoneMetaItem`, `MetaLink`, `HoverMetaLink`, `Credit`, `CreditLink`, `HoverCreditLink`                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `Hero`                  | `Visual`, `Stack`, `Copy`, `Title`, `Tagline`, `Actions`, `Action`, `HoverAction`, `PrimaryAction`, `SecondaryAction`, `MinimalAction`, `ActionIcon`                                                                                                                                                                                                                                                                                                                                                           |
+| `Hero`                  | `Visual`, `DarkVisual`, `LightVisual`, `Stack`, `Copy`, `Title`, `Tagline`, `Actions`, `Action`, `HoverAction`, `PrimaryAction`, `SecondaryAction`, `MinimalAction`, `ActionIcon`                                                                                                                                                                                                                                                                                                                              |
 | `LanguageSelect`        | `Label`, `HoverLabel`, `LabelIcon`, `Select`, `Caret`, `Option`                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | `Logo`                  | `Svg`, `Mark`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 | `SiteLogo`              | `Image`, `Light`, `Dark`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
@@ -473,7 +481,7 @@ sub-elements:
 | `Preview`               | `Caption`, `Stage`, `Frame`, `Code`, `Summary`, `Pre`                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 | `Sidebar`               | `Backdrop`, `OpenBackdrop`, `MobileHeading`, `HomeLink`, `HomeLogo`, `HomeLabel`, `Close`, `HoverClose`, `CloseIcon`, `CurrentLink`, `OpenPane`, `EnteredPane`, `Content`, `Tree`, `List`, `Item`, `TopLevelSpacing`, `GroupSpacing`, `NestedItem`, `SectionHeading`, `Control`, `Summary`, `GroupLabel`, `GroupLabelText`, `Link`, `LinkLabel`, `InteractiveControl`, `SummaryMarker`, `Caret`, `ExpandedCaret`, `LinkedSummary`, `GroupLink`, `LinkedSectionHeading`, `SectionLink`, `Badge`, `TopLevelLink` |
 | `SocialIcons`           | `Link`, `HoverLink`, `Icon`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `StarlightHeader`       | `Primary`, `TitleAndSearch`, `Title`, `LogoLink`, `Logo`, `SiteTitle`, `Search`, `SearchElement`, `Tools`, `ToolItem`, `Social`, `MobileTheme`                                                                                                                                                                                                                                                                                                                                                                 |
+| `Header`                | `Primary`, `TitleAndSearch`, `Title`, `LogoLink`, `Logo`, `SiteTitle`, `Search`, `SearchElement`, `Tools`, `ToolItem`, `Social`, `MobileTheme`                                                                                                                                                                                                                                                                                                                                                                 |
 | `TableOfContentsLayout` | `WithMobile`, `Content`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | `SearchButton`          | `PendingShortcut`, `Label`, `Shortcut`, `Hover`, `Active`, `NativeIcon`, `Icon`                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | `Layout`                | `Islands`, `LockedPage`, `Light`, `Auto`                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
@@ -486,20 +494,16 @@ sub-elements:
 | `TableOfContents`       | `Heading`, `List`, `Item`, `Link`, `LinkLabel`, `HoverLink`, `CurrentLink`                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | `ThemeSelect`           | `Trigger`, `HoverTrigger`, `ActiveTrigger`, `Icon`, `Panel`, `OpenPanel`, `Section`, `SectionSpacing`, `SectionLabel`, `Option`, `HoverOption`, `CheckedOption`, `FocusedOption`, `Input`, `OptionIcon`, `Checkmark`, `SelectedCheckmark`                                                                                                                                                                                                                                                                      |
 | `TopNavigation`         | `Scrollbar`, `Link`, `HoverLink`, `CurrentLink`, `ActiveIndicator`                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| `Document`              | `All`, `Body`, `Control`, `Pointer`, `ResponsiveWidth`, `ResponsiveHeight`, `Hidden`, `DesktopBlock`, `DesktopFlex`, `ScreenReaderOnly`, `Strong`, `Link`, `NarrowBlock`, `MobileBlock`, `Code`, `FocusRing`, `CurrentLink`, `SearchOpen`                                                                                                                                                                                                                                                                      |
+| `Document`              | `All`, `Body`, `Control`, `Pointer`, `ResponsiveWidth`, `ResponsiveHeight`, `Hidden`, `PrintHidden`, `DesktopBlock`, `DesktopFlex`, `ScreenReaderOnly`, `Strong`, `Link`, `NarrowBlock`, `MobileBlock`, `Code`, `FocusRing`, `CurrentLink`, `SearchOpen`                                                                                                                                                                                                                                                       |
 | `MainPane`              | `WithSidebars`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | `MainContent`           | `ContentSpacing`, `Container`, `Panel`, `FirstPanel`, `BodyPanel`                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 | `Banner`                | `Link`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | `SkipLink`              | `Focus`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | `Search`                | `Status`, `Dialog`, `CloseIcon`, `OpenDialog`, `Backdrop`, `Frame`, `Container`, `Close`, `HoverClose`, `ActiveClose`                                                                                                                                                                                                                                                                                                                                                                                          |
-| `Pagination`            | `Link`, `NextLink`, `NextIcon`, `NextLabel`, `HoverLink`, `ActiveLink`, `Title`, `LoneNextLink`, `NativeIcon`, `Icon`, `PreviousIconRtl`, `NextIconRtl`                                                                                                                                                                                                                                                                                                                                                        |
+| `Pagination`            | `Link`, `PreviousLink`, `NextLink`, `NextIcon`, `NextLabel`, `HoverLink`, `ActiveLink`, `Title`, `LoneNextLink`, `Icon`, `PreviousIconRtl`, `NextIconRtl`                                                                                                                                                                                                                                                                                                                                                      |
 | `Markdown`              | `Block`, `BlockSpacing`, `HeadingSpacing`, `List`, `CompactItem`, `ListItem`, `DefinitionTerm`, `DefinitionDescription`, `Link`, `HoverLink`, `Quote`, `Rule`, `Details`, `HoverDetails`, `Summary`, `OpenSummary`, `SummaryMarker`, `SummaryIcon`, `OpenSummaryIcon`, `Code`                                                                                                                                                                                                                                  |
 | `MermaidSource`         | None                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| `StarlightAside`        | `Note`, `Tip`, `Caution`, `Danger`, `Title`, `Icon`, `FirstContent`                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| `StarlightCard`         | `Title`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `StarlightLinkCard`     | `Hover`, `Stack`, `Link`, `LinkOverlay`, `DescriptionAndIcon`                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `StarlightBadge`        | None                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| `StarlightSteps`        | `Item`, `Counter`, `Connector`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `MarkdownAlert`         | `Note`, `Tip`, `Caution`, `Danger`, `Title`, `FirstContent`                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | `SyntaxHighlight`       | `Scroll`, `Wrap`, `Marker`, `Comment`, `Punctuation`, `Keyword`, `String`, `Token`, `Property`, `Number`, `Function`, `Value`, `Operator`, `Text`, `Bg`, `Inserted`, `Deleted`, `Italic`, `Strong`, `Underline`                                                                                                                                                                                                                                                                                                |
 | `SearchResults`         | `Form`, `Input`, `Clear`, `Results`, `Result`, `ResultLink`, `SearchIcon`, `ClearIcon`, `SuppressedClear`, `Message`, `List`, `Title`, `Excerpt`, `NestedResult`, `Match`, `More`, `HoverMore`                                                                                                                                                                                                                                                                                                                 |
 
@@ -599,7 +603,7 @@ source.
 Import styling tools from `@tenphi/cookbook/styling`. They use the same Tasty
 runtime as Cookbook, with its semantic colors, typography presets, units, and
 responsive states. The renderer package also exposes them from
-`@tenphi/starlight/styling`.
+`@tenphi/renderer/styling`.
 
 | Export                   | Purpose                                                                            |
 | ------------------------ | ---------------------------------------------------------------------------------- |
@@ -665,6 +669,7 @@ separately for square artwork; the default Cookbook icon set remains in place
 until changed. `Logo` remains available as the standalone Cookbook book mark.
 
 The built-in mark uses `theme.palette["logo-surface"]` and `theme.palette["logo-mark"]`.
+The default homepage hero artwork also uses `logo-surface` for its brand fill.
 Both default to Glaze `mode: "fixed"`: the brand background and light book keep
 their polarity in dark mode while respecting Glaze's tone boundaries and
 high-contrast settings. The mark-to-background contrast floor is 3:1 normally
@@ -690,7 +695,7 @@ theme: {
 Custom image assets keep their authored colors; use `light`/`dark` files when
 you want distinct artwork. Header and drawer home links center logos with the
 site title regardless of their aspect ratio. Use `theme.styles.SiteLogo` for
-image size and `theme.styles.StarlightHeader.SiteTitle` / `Sidebar.HomeLink`
+image size and `theme.styles.Header.SiteTitle` / `Sidebar.HomeLink`
 for typography; they do not need baseline offsets for a different preset.
 
 ### Advanced site title markup
@@ -738,7 +743,7 @@ Then create `docs/components/SiteTitle.astro`, using an SVG whose paths use
 import ProjectLogo from "../../public/logo.svg";
 import { SiteTitleRoot } from "./site-title.js";
 
-const { siteTitle, siteTitleHref } = Astro.locals.starlightRoute;
+const { siteTitle, siteTitleHref } = Astro.locals.cookbookRoute;
 ---
 
 <SiteTitleRoot href={siteTitleHref}>
@@ -817,7 +822,7 @@ components using the compatibility bridge described above.
 
 `@tenphi/cookbook/eslint-plugin` re-exports the Tasty ESLint plugin together with
 Cookbook's `validationConfig`. The renderer offers the same exports from
-`@tenphi/starlight/eslint-plugin`. Keep style definitions in `.ts` or `.tsx`
+`@tenphi/renderer/eslint-plugin`. Keep style definitions in `.ts` or `.tsx`
 modules, as in the site title example above, to lint them with either ESLint or
 oxlint.
 
@@ -829,7 +834,7 @@ export default {
 };
 ```
 
-Renderer-only consumers can use `extends: "@tenphi/starlight"` instead.
+Renderer-only consumers can use `extends: "@tenphi/renderer"` instead.
 The preset registers both Cookbook styling import paths, its built-in tokens,
 units, responsive states, and typography presets. It also describes
 `defineComponent`, `resolveComponentStyles`, and `mergeStyles`, so their inline
@@ -927,7 +932,7 @@ output.
 The header uses `#header`, generated from `theme.palette.header` (or the page
 surface) at 70% opacity in all four appearance modes, with a 16px backdrop blur.
 Customize the outer bar with `theme.styles.HeaderFrame`, its contents with
-`StarlightHeader`, and header buttons with `HeaderLinks` and `SearchButton`.
+`Header`, and header buttons with `HeaderLinks` and `SearchButton`.
 
 Below 50rem, page navigation moves into a header row and opens a left drawer.
 `MobileMenuToggle.Section` and `Page` style its breadcrumb labels. The drawer
@@ -1108,7 +1113,7 @@ directly to Tasty `#name` tokens. `COOKBOOK_PALETTE_NAMES`, exported from
 | Area                | Roles                                                                                                                                                                                                           |
 | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Surfaces            | `surface`, `header`, `overlay`, `surface-2`, `surface-3`, `surface-2-hover`, `surface-2-pressed`, `surface-3-hover`, `surface-3-pressed`                                                                        |
-| Reading             | `text`, `heading`, `text-soft` (alias `textSoft`), `text-muted`                                                                                                                                                 |
+| Reading             | `text`, `heading`, `text-soft` (alias `textSoft`), `text-muted`, `sidebar-text`                                                                                                                                 |
 | Brand and focus     | `accent-text`, `accent-surface`, `accent-surface-text`, `accent-surface-subtle`, `accent-surface-2-subtle`, `logo-surface`, `logo-mark`, `focus`                                                                |
 | Borders and effects | `border`, `border-strong`, `shadow`, `clear`                                                                                                                                                                    |
 | Status              | `info`, `success`, `warning`, `danger`, each with `-text` and `-surface` variants                                                                                                                               |
@@ -1134,9 +1139,10 @@ backgrounds, typography, or layout.
 A `DOCS_SEMANTIC_CONTRAST_UNMET` or `DOCS_BRAND_CONTRAST_UNMET` error names the
 pair, mode, and required target. Adjust that pair's `theme.palette` declarations:
 use an absolute tone for reading text, reduce saturation when needed, and keep
-`autoFlip` enabled when the solver needs to cross its base. A fixed middle-tone
-button fill may make its label's contrast impossible. Cookbook's default
-brand fill adapts to avoid this, including for orange, yellow, and pale brands.
+`autoFlip` enabled when the solver needs to cross its base. Cookbook's default
+fixed brand fill is anchored to a light label and darkens when needed to meet
+contrast, including for orange, yellow, and pale brands. A custom fixed
+middle-tone fill can make its label's contrast impossible.
 Focus uses a WCAG 3:1 floor (4.5:1 in high contrast) against the surface ramp.
 
 Keep contrast requirements when adjusting colors. Extreme custom tone windows,
@@ -1165,8 +1171,8 @@ theme: {
 and accessibility utilities. `MainPane` and `MainContent` own the content
 layout. `Markdown` owns prose, lists, links, quotations, and disclosure
 anatomy. `Search` owns the dialog; `SearchResults` owns the Pagefind UI.
-The `Starlight*` trees style compatible upstream component markup; Cookbook's
-own `Card`, `Callout`, and `Steps` use their respective trees.
+`MarkdownAlert` styles rendered alert blockquotes; `Card`, `Callout`, and
+`Steps` style Cookbook components.
 
 Custom components created with `defineComponent()` receive `theme.customStyles`
 overrides during server rendering. Units, recipes, states, and presets are

package/docs/troubleshooting.md

@@ -49,15 +49,13 @@ contrast. Browser checks complement the numeric diagnostics.
 
 ## Incompatible plugins
 
-Use the [tested plugin matrix](./plugins.md#verified-compatibility). Cookbook
-owns content routing and all rendered styles. Plugins that read Astro's docs
-collection filesystem or inject CSS are not automatically compatible.
-`starlight-github-alerts` requires the documented unified Markdown processor;
-`starlight-links-validator` is unsupported because it reads synthetic paths.
-Use Cookbook's graph and built-output checks for links.
-
-For your own plugin, read custom frontmatter through route middleware or the
-server-only `@tenphi/cookbook/content` API. If a schema rejects data, check that
+Cookbook owns content routing and all rendered styles. Plugins that assume a
+different docs collection or inject CSS cannot run in the renderer. GitHub
+alerts are supported directly; use Cookbook's graph and built-output checks
+for links. See [extending Cookbook](./plugins.md) for Astro Markdown plugins.
+
+Read custom frontmatter through the server-only `@tenphi/cookbook/content` API
+or `Astro.locals.cookbookRoute` in a component override. If a schema rejects data, check that
 custom fields do not replace reserved Cookbook frontmatter and that parsed
 values are JSON-safe. A plugin's successful registration is not proof that its
 rendered output works.

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@tenphi/cookbook",
-  "version": "0.18.1",
+  "version": "0.19.0",
   "description": "Repository-native static documentation for Astro",
   "type": "module",
   "keywords": [
     "astro-integration",
     "astro",
     "documentation",
-    "starlight",
+    "documentation",
     "static-site"
   ],
   "bin": {
@@ -68,8 +68,8 @@
   "author": "Andrey Yamanov",
   "license": "MIT",
   "dependencies": {
-    "@tenphi/docs": "0.18.1",
-    "@tenphi/starlight": "0.18.1"
+    "@tenphi/docs": "0.19.0",
+    "@tenphi/renderer": "0.19.0"
   },
   "peerDependencies": {
     "astro": "^7.3.2"

package/docs/starlight-comparison.md

@@ -1,124 +0,0 @@
----
-title: Cookbook and Starlight
-description: Understand which Starlight authoring conventions Cookbook preserves and where its repository and theme model differs.
-sidebar:
-  order: 5
----
-Cookbook uses [Astro Starlight](https://starlight.astro.build/) as its
-documentation shell. It keeps familiar page-authoring conventions while adding
-repository and npm content sources, stricter validation, and a Tasty/Glaze
-theme model.
-
-## Cookbook or Starlight?
-
-Start with the place where the documentation must live. Starlight is a strong
-choice when an Astro site owns its content. Cookbook is designed for projects
-where the repository Markdown—or the documentation actually published in an
-npm package—must remain the source of truth.
-
-| Concern                 | Starlight                                                                          | Cookbook                                                                                                                                                                              |
-| ----------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Starting point          | Add Starlight to an Astro project and author its documentation content collection. | Add one integration to an Astro project, or generate a complete site directly from a published npm package.                                                                           |
-| Content ownership       | The documentation site conventionally owns its Markdown under `src/content/docs/`. | Reads `README.md`, repository `docs/` trees, files outside the Astro app, and selected files from npm artifacts without copying or rewriting them.                                    |
-| Reproducible releases   | Follows the dependencies and content committed with the site.                      | Can lock an npm package to its exact resolved version and integrity, then rebuild from the files users actually receive.                                                              |
-| Build guarantees        | Provides Starlight's content schema and Astro build pipeline.                      | Adds strict checks for duplicate routes, broken links, missing assets, unsafe paths, and invalid navigation with source-aware diagnostics.                                            |
-| Design system           | Supports CSS variables, custom CSS, and component overrides.                       | Exposes the full [Tasty styling DSL](./upstream/tasty/docs/dsl.md) through configuration, with Glaze-generated semantic colors and named style trees for Cookbook and shell surfaces. |
-| Familiar authoring      | Defines the Starlight page, navigation, i18n, and frontmatter conventions.         | Preserves those conventions—including splash pages, locales, edit links, and last-updated metadata—while resolving them against each original source.                                 |
-| Structural escape hatch | Replaces Starlight components when markup or behavior must change.                 | Supports Astro component overrides for structural changes; visual changes normally stay in typed `theme` configuration.                                                               |
-
-Choose Starlight when the documentation site is the natural home for the
-content and its CSS-oriented customization model fits the project. Choose
-Cookbook when documentation must stay beside the code, match a published
-package, fail strictly when references drift, or expose a reusable design
-system entirely through configuration.
-
-## Customize with Tasty's DSL
-
-Cookbook customization is not limited to replacing token values. Every entry
-under `theme.styles` is a partial Tasty style object that Cookbook merges into
-the component's base style tree. That gives configuration access to the same
-responsive values, state maps, calculations, semantic tokens, typography
-presets, and named sub-elements used by Cookbook itself:
-
-```ts
-export default defineDocsConfig({
-  theme: {
-    states: {
-      "@touch": "@media(pointer: coarse)",
-    },
-    styles: {
-      MarkdownCodeBlock: {
-        Pre: {
-          padding: {
-            "": "2x 4x",
-            "@mobile": "1.5x 3x",
-          },
-          radius: "$card-radius",
-        },
-        CopyButton: {
-          inlineSize: {
-            "": "2rem",
-            "@touch": "2.5rem",
-          },
-          scale: {
-            "": "1",
-            ":active": "0.94",
-          },
-        },
-      },
-    },
-  },
-});
-```
-
-The user supplies only overrides; the merge happens inside Cookbook. See
-[Theme and components](./theme-and-components.md#style-customization) for the
-complete component and sub-element inventory, and the
-[Tasty documentation](./upstream/tasty/docs/README.md) for the DSL's properties and
-conditional syntax. Structural Astro overrides remain available when a change
-requires different markup or behavior rather than styling.
-
-## Configure the shared capabilities
-
-```ts
-export default defineDocsConfig({
-  editLink: {
-    baseUrl: "https://github.com/example/project/edit/main/",
-  },
-  lastUpdated: true,
-  locales: {
-    root: { label: "English", lang: "en" },
-    fr: { label: "Français", lang: "fr" },
-  },
-  defaultLocale: "root",
-});
-```
-
-The keys deliberately match Starlight so an existing Starlight author does not
-need to relearn page metadata or i18n. Cookbook resolves edit and Git metadata
-before handing each page to Starlight because its source may live in a root
-`docs/` directory, outside the Astro app, or inside a locked npm artifact.
-
-## Create a splash page
-
-```yaml
----
-title: Example
-template: splash
-hero:
-  title: Build something clear.
-  tagline: A short explanation of the value your project provides.
-  actions:
-    - text: Get started
-      link: /getting-started/
-      variant: primary
-    - text: View API
-      link: /reference/
-      variant: secondary
----
-```
-
-Use `template: doc` (the default) for conventional reference pages. See
-Starlight's [page guide](https://starlight.astro.build/guides/pages/) for the
-authoring model Cookbook builds on, then use [Theme and
-components](./theme-and-components.md) for Cookbook-specific styling.