@elcoosp/docs-toolkit 0.0.0-stage → 0.5.1

package/src/config/index.ts

@@ -0,0 +1,183 @@
+import fs from 'node:fs';
+import { ROBOTO_BASE64 } from '../assets/font-b64';
+import { fileURLToPath } from 'node:url';
+import { defineConfig } from 'astro/config';
+import type { AstroUserConfig } from 'astro';
+import starlight from '@astrojs/starlight';
+import type { StarlightUserConfig } from '@astrojs/starlight/types';
+import astroTakumi from 'astro-takumi';
+import { makeRender } from '../og/og-render';
+import { deriveAccent } from '../og/accent';
+import { resolveLlmsConfig, llmsIntegration, llmsHeadLink } from './llms';
+import type { LlmsTxtConfig } from './llms';
+import { changelogIntegration } from './changelog/integration';
+import type { ChangelogConfig } from './changelog/types';
+
+import starlightTelescope from 'starlight-telescope';
+import starlightFullviewMode from 'starlight-fullview-mode';
+import starlightTags from 'starlight-tags';
+import starlightScrollToTop from 'starlight-scroll-to-top';
+import starlightAnnouncement from 'starlight-announcement';
+
+import starlightSeo from 'starlight-seo';
+import starlightBlog from 'starlight-blog';
+import starlightGiscus from 'starlight-giscus';
+import mermaid from 'astro-mermaid';
+
+
+
+export type { LlmsTxtConfig } from './llms';
+export type { ChangelogConfig, Release } from './changelog/types';
+export { DEFAULT_SECTIONS as DEFAULT_LLMS_SETS, detectSections } from './llms';
+
+export interface DocsConfigOptions {
+  site: string;
+  domain: string;
+  title: string;
+  projectName?: string;
+  description: string;
+  logoPath?: string;
+  favicon?: string;
+  customCss?: string[];
+  social?: StarlightUserConfig['social'];
+  editLink?: StarlightUserConfig['editLink'];
+  locales?: StarlightUserConfig['locales'];
+  defaultLocale?: StarlightUserConfig['defaultLocale'];
+  plugins?: StarlightUserConfig['plugins'];
+  sidebar: StarlightUserConfig['sidebar'];
+  routeMiddleware?: string;
+  base?: string;
+  accentOverride?: string;
+  expressiveCode?: StarlightUserConfig['expressiveCode'];
+  extraStarlight?: Partial<StarlightUserConfig>;
+  extraIntegrations?: NonNullable<AstroUserConfig['integrations']>;
+  extraVite?: Record<string, unknown>;
+  /** Configure starlight-llms-txt. `false` disables the plugin entirely. */
+  llmsTxt?: LlmsTxtConfig | false;
+  giscus?: any;
+  changelog?: ChangelogConfig;
+}
+
+export async function defineDocsConfig(
+  options: DocsConfigOptions,
+): Promise<AstroUserConfig> {
+  const {
+    site,
+    domain,
+    title,
+    projectName = title,
+    description,
+    logoPath = './src/assets/logo.png',
+    favicon = '/favicon.png',
+    customCss = ['./src/styles/custom.css'],
+    social = [],
+    editLink,
+    locales,
+    defaultLocale = 'root',
+    plugins = [],
+    sidebar,
+    routeMiddleware = './src/routeData.ts',
+    base,
+    accentOverride,
+    expressiveCode = { themes: ['github-light', 'github-dark'] },
+    extraStarlight = {},
+    extraIntegrations = [],
+    extraVite = {},
+    llmsTxt = {},
+    changelog,
+  } = options;
+
+  const accent = accentOverride
+    ? { hex: accentOverride, hexA12: accentOverride + '1a' }
+    : await deriveAccent(logoPath);
+
+  const logoB64 = fs.readFileSync(logoPath).toString('base64');
+  const render = makeRender({
+    logoDataUrl: 'data:image/png;base64,' + logoB64,
+    accentHex: accent.hex,
+    accentHexA12: accent.hexA12,
+    domain,
+    projectName,
+  });
+
+  const fontBuf = Buffer.from(ROBOTO_BASE64, 'base64');
+
+  const starlightPlugins = [...plugins];
+
+
+  const sidebarWithChangelog = changelog
+    ? [...sidebar, { label: changelog.sidebarLabel ?? 'Changelog', link: changelog.pagePath ?? '/changelog/' }]
+    : sidebar;
+
+  let headLink: any = undefined;
+  let resolvedLlms: any = undefined;
+  if (llmsTxt !== false) {
+    resolvedLlms = resolveLlmsConfig(llmsTxt ?? {}, { title, description, site, source: undefined });
+    if (resolvedLlms.outputs.headLink) headLink = llmsHeadLink();
+  }
+
+  const starlightOptions: StarlightUserConfig = {
+    components: {
+      PageTitle: '@elcoosp/docs-toolkit/PageActions.astro',
+    },
+    routeMiddleware,
+    expressiveCode,
+    title,
+    description,
+    logo: { src: logoPath },
+    favicon,
+    customCss,
+    social,
+    ...(editLink ? { editLink } : {}),
+    ...(locales ? { locales } : {}),
+    ...(defaultLocale ? { defaultLocale } : {}),
+    plugins: starlightPlugins,
+    ...(changelog ? { head: [{ tag: 'link', attrs: { rel: 'alternate', type: 'application/rss+xml', title: changelog.pageTitle ?? `${title} changelog`, href: changelog.rssPath ?? '/changelog.xml' } }] } : {}),
+    head: [...((extraStarlight as any)?.head ?? []), ...(headLink ? [headLink] : [])],
+    sidebar: sidebarWithChangelog,
+    ...extraStarlight,
+  };
+
+  const integrations: NonNullable<AstroUserConfig['integrations']> = [
+    mermaid(), // MUST be before starlight
+    starlight(starlightOptions),
+    ...extraIntegrations,
+    astroTakumi({
+      options: {
+        domBackend: 'linkedom',
+        fonts: [fontBuf],
+        width: 1200,
+        height: 630,
+        format: 'png',
+      },
+      render,
+    } as unknown as Parameters<typeof astroTakumi>[0]),
+  ];
+
+  if (llmsTxt !== false && resolvedLlms) {
+    integrations.push(llmsIntegration(resolvedLlms));
+  }
+
+  if (changelog) {
+    integrations.push(
+      changelogIntegration({
+        repo: changelog.repo,
+        changelogPath: changelog.changelogPath ?? '../CHANGELOG.md',
+        pagePath: changelog.pagePath ?? '/changelog',
+        rssPath: changelog.rssPath ?? '/changelog.xml',
+        sidebarLabel: changelog.sidebarLabel ?? 'Changelog',
+        pageTitle: changelog.pageTitle ?? `${title} changelog`,
+        description: changelog.description ?? description,
+        disableRss: changelog.disableRss ?? false,
+        disablePage: changelog.disablePage ?? false,
+      }),
+    );
+  }
+
+  return defineConfig({
+    vite: { ssr: { external: ['jsdom', 'astro-takumi'], noExternal: ['starlight-llms-txt'] }, ...extraVite },
+    ...(site ? { site } : {}),
+    ...(base ? { base } : {}),
+    integrations,
+  });
+}

package/src/config/llms/collect.ts

@@ -0,0 +1,66 @@
+import { readdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { PageEntry } from './types.js';
+
+const TITLE_RE = /^title:\s*(?:["'](.+?)["']|(.+?))\s*$/m;
+const DESC_RE = /^description:\s*(?:["'](.+?)["']|(.+?))\s*$/m;
+const TYPE_RE = /^type:\s*(?:["'](.+?)["']|(.+?))\s*$/m;
+const ORDER_RE = /^order:\s*(\d+)/;
+
+function stripFrontmatter(text: string) {
+  const m = text.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
+  if (!m) return { fm: '', body: text };
+  return { fm: m[1], body: text.slice(m[0].length) };
+}
+
+function cleanBody(body: string) {
+  return body
+    .replace(/^import\s+.*?;?\s*$/gm, '')
+    .replace(/<\/?(Card|CardGrid|LinkCard|Tabs|TabItem|Steps|FileTree|Aside|Badge)[^>]*>/g, '')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim();
+}
+
+export function collectPages(contentRoot: string): PageEntry[] {
+  const pages: PageEntry[] = [];
+  function walk(dir: string, prefix: string) {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (entry.name.startsWith('.')) continue;
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk(full, prefix + entry.name + '/');
+      } else if (/\.(md|mdx)$/.test(entry.name)) {
+        const rel = prefix + entry.name;
+        const raw = readFileSync(full, 'utf8');
+        const { fm, body } = stripFrontmatter(raw);
+
+        const titleMatch = fm.match(TITLE_RE);
+        const title = (titleMatch?.[1] || titleMatch?.[2] || entry.name.replace(/\.(md|mdx)$/, '')).trim();
+
+        const descMatch = fm.match(DESC_RE);
+        const description = (descMatch?.[1] || descMatch?.[2] || '').trim();
+
+        const typeMatch = fm.match(TYPE_RE);
+        const type = (typeMatch?.[1] || typeMatch?.[2] || '').trim();
+
+        const orderMatch = fm.match(ORDER_RE);
+        const order = orderMatch ? Number(orderMatch[1]) : 99;
+
+        const noExt = rel.replace(/\.(md|mdx)$/, '');
+        const slug = noExt === 'index' ? 'index' : noExt;
+        const route = slug === 'index' ? '/' : `/${slug}/`;
+        const markdownRoute = slug === 'index' ? '/index.md' : `/${slug}.md`;
+        const section = slug === 'index' ? 'Overview' : humanizeDir(slug.split('/')[0]);
+
+        pages.push({ slug, route, markdownRoute, title, description, type, order, section, body: cleanBody(body) });
+      }
+    }
+  }
+
+  function humanizeDir(d: string) {
+     return d.split(/[-_]/).map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(' ');
+  }
+
+  walk(contentRoot, '');
+  return pages.sort((a, b) => a.order - b.order || a.title.localeCompare(b.title));
+}

package/src/config/llms/config.ts

@@ -0,0 +1,24 @@
+import { LlmsTxtConfig, ResolvedLlmsConfig } from './types.js';
+import { detectSections, DEFAULT_SECTIONS } from './sections.js';
+
+export function resolveLlmsConfig(input: LlmsTxtConfig, ctx: { title: string, description: string, site?: string, source?: string }): ResolvedLlmsConfig {
+  const sets = input.sets || detectSections() || DEFAULT_SECTIONS;
+  return {
+    title: input.title ?? ctx.title,
+    description: input.description ?? ctx.description,
+    url: input.url ?? ctx.site ?? '',
+    source: input.source ?? ctx.source ?? '',
+    sets,
+    exclude: input.exclude ?? [],
+    optional: input.optional ?? [],
+    outputs: {
+      index: input.outputs?.index ?? true,
+      full: input.outputs?.full ?? true,
+      small: input.outputs?.small ?? true,
+      json: input.outputs?.json ?? true,       // Default TRUE for state-of-the-art
+      pages: input.outputs?.pages ?? true,     // Default TRUE for state-of-the-art
+      robots: input.outputs?.robots ?? true,
+      headLink: input.outputs?.headLink ?? true,
+    }
+  };
+}

package/src/config/llms/emit.ts

@@ -0,0 +1,56 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { PageEntry, ResolvedLlmsConfig } from './types.js';
+import { renderIndex } from './render/index.js';
+import { renderFull } from './render/full.js';
+import { renderSmall } from './render/small.js';
+import { renderJson } from './render/json.js';
+import { renderPageMd } from './render/page.js';
+
+export function emitAll(
+  distDir: string,
+  pages: PageEntry[],
+  cfg: ResolvedLlmsConfig,
+  log: (msg: string) => void = console.log,
+): void {
+  const safeWrite = (file: string, fn: () => string) => {
+    try {
+      const content = fn();
+      const p = path.join(distDir, file);
+      fs.mkdirSync(path.dirname(p), { recursive: true });
+      fs.writeFileSync(p, content);
+      log(`  ✓ ${file} (${content.length} bytes)`);
+    } catch (e) {
+      log(`  ✗ ${file} — ${e instanceof Error ? e.message : String(e)}`);
+    }
+  };
+
+  if (cfg.outputs.index) safeWrite('llms.txt', () => renderIndex(pages, cfg));
+  if (cfg.outputs.full) safeWrite('llms-full.txt', () => renderFull(pages, cfg));
+  if (cfg.outputs.small) safeWrite('llms-small.txt', () => renderSmall(pages, cfg));
+  if (cfg.outputs.json) safeWrite('llms.json', () => renderJson(pages, cfg));
+
+  if (cfg.outputs.pages) {
+    for (const p of pages) {
+      const target = p.slug === 'index' ? 'index.md' : `${p.slug}.md`;
+      safeWrite(target, () => renderPageMd(p));
+    }
+  }
+
+  if (cfg.outputs.robots) {
+    try {
+      const robotsPath = path.join(distDir, 'robots.txt');
+      const line = 'LLM: /llms.txt\n';
+      if (fs.existsSync(robotsPath)) {
+        const content = fs.readFileSync(robotsPath, 'utf8');
+        if (!content.includes('LLM:')) fs.appendFileSync(robotsPath, `\n${line}`);
+        log('  ✓ robots.txt (appended LLM: /llms.txt)');
+      } else {
+        fs.writeFileSync(robotsPath, line);
+        log('  ✓ robots.txt (created)');
+      }
+    } catch (e) {
+      log(`  ✗ robots.txt — ${e instanceof Error ? e.message : String(e)}`);
+    }
+  }
+}

package/src/config/llms/head.ts

@@ -0,0 +1,6 @@
+export function llmsHeadLink() {
+  return {
+    tag: 'link',
+    attrs: { rel: 'llms-txt', href: '/llms.txt' }
+  };
+}

package/src/config/llms/index.ts

@@ -0,0 +1,5 @@
+export * from './types.js';
+export * from './sections.js';
+export * from './config.js';
+export * from './integration.js';
+export * from './head.js';

package/src/config/llms/integration.ts

@@ -0,0 +1,26 @@
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import type { AstroIntegration } from 'astro';
+import { ResolvedLlmsConfig } from './types.js';
+import { collectPages } from './collect.js';
+import { emitAll } from './emit.js';
+
+export function llmsIntegration(cfg: ResolvedLlmsConfig): AstroIntegration {
+  return {
+    name: '@elcoosp/docs-toolkit/llms',
+    hooks: {
+      'astro:build:done': async ({ dir, logger }) => {
+        const distDir = fileURLToPath(dir);
+        const contentRoot = path.resolve(process.cwd(), 'src/content/docs');
+        logger.info('llms: collecting pages...');
+        try {
+          const pages = collectPages(contentRoot);
+          logger.info(`llms: ${pages.length} pages collected`);
+          emitAll(distDir, pages, cfg, (msg) => logger.info(`llms:${msg}`));
+        } catch (e) {
+          logger.error(`llms: FAILED — ${e instanceof Error ? e.stack : String(e)}`);
+        }
+      }
+    }
+  };
+}

package/src/config/llms/render/full.ts

@@ -0,0 +1,11 @@
+import { PageEntry, ResolvedLlmsConfig } from '../types.js';
+
+export function renderFull(pages: PageEntry[], cfg: ResolvedLlmsConfig): string {
+  let out = `# ${cfg.title} — full documentation\n\n> ${cfg.description}\n\nSource: ${cfg.source}\n\n`;
+  for (const p of pages) {
+    out += `---\n\n# ${p.title}\n\n`;
+    if (p.description) out += `${p.description}\n\n`;
+    out += `${p.body}\n\n`;
+  }
+  return out.trim() + '\n';
+}

package/src/config/llms/render/index.ts

@@ -0,0 +1,25 @@
+import { PageEntry, ResolvedLlmsConfig } from '../types.js';
+
+export function renderIndex(pages: PageEntry[], cfg: ResolvedLlmsConfig): string {
+  let out = `# ${cfg.title}\n\n> ${cfg.description}\n\nSource: ${cfg.source}\n`;
+
+  const sections = [...new Set(pages.map(p => p.section))].filter(s => s !== 'Overview' && s !== 'Optional');
+
+  for (const section of sections) {
+    const group = pages.filter(p => p.section === section);
+    out += `\n## ${section}\n\n`;
+    for (const p of group) {
+      out += `- [${p.title}](${cfg.url}${p.route}): ${p.description}\n`;
+    }
+  }
+
+  const optional = pages.filter(p => p.section === 'Optional' || cfg.optional.includes(p.slug));
+  if (optional.length > 0) {
+    out += `\n## Optional\n\n`;
+    for (const p of optional) {
+      out += `- [${p.title}](${cfg.url}${p.route}): ${p.description}\n`;
+    }
+  }
+
+  return out.trim() + '\n';
+}

package/src/config/llms/render/json.ts

@@ -0,0 +1,21 @@
+import { PageEntry, ResolvedLlmsConfig } from '../types.js';
+
+export function renderJson(pages: PageEntry[], cfg: ResolvedLlmsConfig): string {
+  return JSON.stringify({
+    $schema: "https://llmstxt.org/schema.json",
+    title: cfg.title,
+    description: cfg.description,
+    url: cfg.url,
+    source: cfg.source,
+    pages: pages.map(p => ({
+      slug: p.slug,
+      route: p.route,
+      markdownRoute: p.markdownRoute,
+      title: p.title,
+      description: p.description,
+      type: p.type,
+      order: p.order,
+      section: p.section
+    }))
+  }, null, 2);
+}

package/src/config/llms/render/page.ts

@@ -0,0 +1,8 @@
+import { PageEntry } from '../types.js';
+
+export function renderPageMd(p: PageEntry): string {
+  let out = `# ${p.title}\n\n`;
+  if (p.description) out += `> ${p.description}\n\n`;
+  out += p.body;
+  return out.trim() + '\n';
+}

package/src/config/llms/render/small.ts

@@ -0,0 +1,8 @@
+import { PageEntry, ResolvedLlmsConfig } from '../types.js';
+import { renderFull } from './full.js';
+
+export function renderSmall(pages: PageEntry[], cfg: ResolvedLlmsConfig): string {
+  // Curated subset: pages with `order: N` where N < 99, OR type === 'overview'
+  const curated = pages.filter(p => p.order < 99 || p.type === 'overview');
+  return renderFull(curated, cfg).replace('— full documentation', '— curated subset');
+}

package/src/config/llms/sections.ts

@@ -0,0 +1,34 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const DEFAULT_SECTIONS = [
+  { label: 'Tutorials', paths: ['tutorials/**'] },
+  { label: 'How-to Guides', paths: ['guides/**'] },
+  { label: 'Reference', paths: ['reference/**'] },
+  { label: 'Explanation', paths: ['explanation/**'] },
+];
+
+export function humanize(name: string): string {
+  return name.split(/[-_]/).map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(' ');
+}
+
+export function detectSections(contentRoot = 'src/content/docs') {
+  try {
+    const entries = fs.readdirSync(contentRoot, { withFileTypes: true });
+    const sections: Array<{ label: string; paths: string[] }> = [];
+    for (const e of entries) {
+      if (!e.isDirectory() || e.name.startsWith('.') || e.name === '_') continue;
+      const hasContent = (function walk(dir: string): boolean {
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+          if (entry.isFile() && /\.(md|mdx)$/.test(entry.name)) return true;
+          if (entry.isDirectory() && walk(path.join(dir, entry.name))) return true;
+        }
+        return false;
+      })(path.join(contentRoot, e.name));
+      if (hasContent) sections.push({ label: humanize(e.name), paths: [`${e.name}/**`] });
+    }
+    return sections.length > 0 ? sections : null;
+  } catch {
+    return null;
+  }
+}

package/src/config/llms/types.ts

@@ -0,0 +1,34 @@
+export interface PageEntry {
+  slug: string;
+  route: string;
+  markdownRoute: string;
+  title: string;
+  description: string;
+  type: string;
+  order: number;
+  section: string;
+  body: string;
+}
+
+export interface LlmsTxtConfig {
+  title?: string;
+  description?: string;
+  url?: string;
+  source?: string;
+  sets?: Array<{ label: string; paths: string[]; description?: string }>;
+  exclude?: string[];
+  optional?: string[];
+  outputs?: {
+    index?: boolean;
+    full?: boolean;
+    small?: boolean;
+    json?: boolean;
+    pages?: boolean;
+    robots?: boolean;
+    headLink?: boolean;
+  };
+}
+
+export interface ResolvedLlmsConfig extends Required<Omit<LlmsTxtConfig, 'outputs'>> {
+  outputs: Required<NonNullable<LlmsTxtConfig['outputs']>>;
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './og';
+export { defineDocsConfig } from './config';
+export type { DocsConfigOptions } from './config';

package/src/og/accent.ts

@@ -0,0 +1,143 @@
+import { readFile } from 'node:fs/promises';
+import sharp from 'sharp';
+
+const clamp = (v: number, lo: number, hi: number): number => Math.max(lo, Math.min(hi, v));
+
+interface Rgb { r: number; g: number; b: number }
+interface Hsl { h: number; s: number; l: number }
+
+function rgbToHsl(r: number, g: number, b: number): Hsl {
+  r /= 255; g /= 255; b /= 255;
+  const mx = Math.max(r, g, b);
+  const mn = Math.min(r, g, b);
+  const l = (mx + mn) / 2;
+  let h = 0;
+  let s = 0;
+  if (mx !== mn) {
+    const d = mx - mn;
+    s = l > 0.5 ? d / (2 - mx - mn) : d / (mx + mn);
+    if (mx === r) h = ((g - b) / d + (g < b ? 6 : 0)) * 60;
+    else if (mx === g) h = ((b - r) / d + 2) * 60;
+    else h = ((r - g) / d + 4) * 60;
+  }
+  return { h: Math.round(h), s: Math.round(s * 100), l: Math.round(l * 100) };
+}
+
+function hslToRgb(h: number, s: number, l: number): [number, number, number] {
+  s /= 100; l /= 100;
+  const c = (1 - Math.abs(2 * l - 1)) * s;
+  const x = c * (1 - Math.abs(((h / 60) % 2) - 1));
+  const m = l - c / 2;
+  let r = 0, g = 0, b = 0;
+  if (h < 60) [r, g, b] = [c, x, 0];
+  else if (h < 120) [r, g, b] = [x, c, 0];
+  else if (h < 180) [r, g, b] = [0, c, x];
+  else if (h < 240) [r, g, b] = [0, x, c];
+  else if (h < 300) [r, g, b] = [x, 0, c];
+  else [r, g, b] = [c, 0, x];
+  return [r, g, b].map((v) => Math.round((v + m) * 255)) as [number, number, number];
+}
+
+const rgbToHex = (r: number, g: number, b: number): string =>
+  '#' + [r, g, b].map((v) => v.toString(16).padStart(2, '0')).join('');
+
+const hslToHex = (h: number, s: number, l: number): string => rgbToHex(...hslToRgb(h, s, l));
+
+export type AccentStyle = 'graydark' | 'chroma' | 'fallback' | 'empty';
+
+export interface AccentHslBand {
+  h: number;
+  s: number;
+  l: number;
+  low: number;
+  high: number;
+}
+
+export interface AccentResult {
+  hex: string;
+  hexA12: string;
+  style: AccentStyle;
+  chroma: number;
+  logoHex: string;
+  hsl: { light: AccentHslBand; dark: AccentHslBand };
+}
+
+export interface DeriveAccentOptions {
+  fallbackHex?: string;
+  style?: AccentStyle;
+}
+
+export async function deriveAccent(
+  logoPath: string,
+  opts: DeriveAccentOptions = {},
+): Promise<AccentResult> {
+  const { fallbackHex = '#404040', style: forceStyle } = opts;
+
+  const fallback = (style: AccentStyle): AccentResult => ({
+    hex: fallbackHex,
+    hexA12: fallbackHex + '1a',
+    style,
+    chroma: 0,
+    logoHex: fallbackHex,
+    hsl: {
+      light: { h: 0, s: 0, l: 25, low: 85, high: 17 },
+      dark: { h: 0, s: 0, l: 75, low: 45, high: 85 },
+    },
+  });
+
+  let logoBuf: Buffer;
+  try {
+    logoBuf = await readFile(logoPath);
+  } catch {
+    return fallback('fallback');
+  }
+
+  const { data } = await sharp(logoBuf)
+    .resize(64, 64, { fit: 'inside' })
+    .ensureAlpha()
+    .raw()
+    .toBuffer({ resolveWithObject: true });
+
+  const px: Rgb[] = [];
+  for (let i = 0; i < data.length; i += 4) {
+    const r = data[i]!;
+    const g = data[i + 1]!;
+    const b = data[i + 2]!;
+    const a = data[i + 3]!;
+    if (a < 128) continue;
+    if (r > 240 && g > 240 && b > 240) continue;
+    if (r < 15 && g < 15 && b < 15) continue;
+    px.push({ r, g, b });
+  }
+  if (px.length === 0) return fallback('empty');
+
+  const med = (['r', 'g', 'b'] as const).map((ch) => {
+    const sorted = px.map((x) => x[ch]).sort((a, b) => a - b);
+    return sorted[Math.floor(sorted.length / 2)]!;
+  }) as [number, number, number];
+
+  const { h, s, l } = rgbToHsl(...med);
+  const chroma = (px.filter((q) => rgbToHsl(q.r, q.g, q.b).s > 15).length / px.length) * 100;
+
+  const style: AccentStyle = forceStyle ?? (chroma < 20 ? 'graydark' : 'chroma');
+
+  const lightL =
+    style === 'graydark' ? clamp(Math.round(l / 5) * 5, 20, 35) : clamp(Math.round(l / 5) * 5, 30, 40);
+  const lightH = style === 'graydark' ? 0 : h;
+  const lightS = style === 'graydark' ? 0 : clamp(Math.round(s / 5) * 5, 45, 70);
+
+  const hex = hslToHex(lightH, lightS, lightL);
+  const darkL = 100 - lightL;
+
+  return {
+    hex,
+    hexA12: hex + '1a',
+    style,
+    chroma: Math.round(chroma),
+    logoHex: rgbToHex(...med),
+    hsl: {
+      light: { h: lightH, s: lightS, l: lightL, low: Math.min(lightL + 60, 95), high: Math.max(lightL - 8, 2) },
+      dark: { h: lightH, s: lightS, l: darkL, low: lightL + 20, high: Math.min(darkL + 10, 98) },
+    },
+  };
+}

package/src/og/index.ts

@@ -0,0 +1,5 @@
+export { makeRender } from './og-render';
+export { deriveAccent } from './accent';
+export type { AccentResult, AccentStyle, AccentHslBand, DeriveAccentOptions } from './accent';
+export { onRequest } from './routeData';
+export type { RouteContext } from './routeData';