@elcoosp/docs-toolkit 0.0.0-stage → 0.5.0

package/src/og/jsx.d.ts

@@ -0,0 +1,11 @@
+import 'react';
+
+// og-render.tsx uses `tw` (Tailwind-in-JSX) attributes on intrinsic elements.
+declare module 'react' {
+  interface HTMLAttributes<T> {
+    tw?: string;
+  }
+  interface SVGAttributes<T> {
+    tw?: string;
+  }
+}

package/src/og/og-render.tsx

@@ -0,0 +1,155 @@
+import React from 'react';
+
+export interface MakeRenderOptions {
+  logoDataUrl: string;
+  accentHex: string;
+  accentHexA12: string;
+  domain: string;
+  projectName: string;
+}
+
+export interface RenderProps {
+  title?: string;
+  description?: string | null;
+  pathname?: string;
+  [key: string]: unknown;
+}
+
+function hexToRgba(hex: string, a: number): string {
+  const r = parseInt(hex.slice(1, 3), 16);
+  const g = parseInt(hex.slice(3, 5), 16);
+  const b = parseInt(hex.slice(5, 7), 16);
+  return `rgba(${r}, ${g}, ${b}, ${a})`;
+}
+
+function getSection(pathname: string): string {
+  const p = "/" + (pathname || "").toLowerCase().replace(/^\/+/, "");
+  if (p.includes("404")) return "404";
+  if (p.startsWith("/tutorials/") || p.startsWith("/getting-started/")) return "Tutorial";
+  if (p.startsWith("/guides/")) return "Guide";
+  if (p.startsWith("/reference/")) return "Reference";
+  if (p.startsWith("/explanation/") || p.startsWith("/concepts/")) return "Explanation";
+  return "Overview";
+}
+
+function computeTitleSize(title: string, description?: string | null): number {
+  const tl = title.length;
+  const dl = description ? description.length : 0;
+  const total = tl + dl;
+  let size;
+  if (tl <= 6) size = 190;
+  else if (tl <= 12) size = 145;
+  else if (tl <= 22) size = 108;
+  else if (tl <= 35) size = 78;
+  else if (tl <= 55) size = 60;
+  else size = 46;
+  if (total > 260) size = Math.min(size, 44);
+  else if (total > 200) size = Math.min(size, 56);
+  else if (total > 150) size = Math.min(size, 70);
+  else if (total > 100) size = Math.min(size, 88);
+  return size;
+}
+
+// Particles clustered toward top-right where the accent glow lives
+const PARTICLES = [
+  // Dense cluster top-right (constellation near glow)
+  { x: 1150, y: 42,  r: 3, o: 0.55 },
+  { x: 1108, y: 78,  r: 2, o: 0.45 },
+  { x: 1172, y: 122, r: 2, o: 0.4 },
+  { x: 1068, y: 156, r: 4, o: 0.32 },
+  { x: 1140, y: 194, r: 2, o: 0.5 },
+  { x: 1080, y: 240, r: 3, o: 0.38 },
+  { x: 1180, y: 278, r: 2, o: 0.42 },
+  { x: 1008, y: 302, r: 2, o: 0.35 },
+  { x: 1112, y: 346, r: 3, o: 0.3 },
+  { x: 1160, y: 400, r: 2, o: 0.45 },
+  // Trailing cluster middle-right (fades outward)
+  { x: 940,  y: 220, r: 2, o: 0.28 },
+  { x: 880,  y: 320, r: 2, o: 0.24 },
+  { x: 820,  y: 140, r: 2, o: 0.22 },
+  { x: 760,  y: 400, r: 3, o: 0.2 },
+  { x: 700,  y: 260, r: 2, o: 0.18 },
+  { x: 1000, y: 480, r: 2, o: 0.22 },
+  { x: 1080, y: 540, r: 3, o: 0.25 },
+  // Sparse left side (barely there)
+  { x: 200,  y: 120, r: 2, o: 0.15 },
+  { x: 340,  y: 480, r: 2, o: 0.15 },
+];
+
+// Grid — vertical full height, horizontal only top 40% (header zone)
+const V_LINES = [108, 208, 308, 408, 508, 608, 708, 808, 908, 1008, 1108];
+const H_LINES_TOP = [90, 180, 270];  // stop above title
+
+export const makeRender = ({ logoDataUrl, accentHex, accentHexA12, domain, projectName }: MakeRenderOptions) => {
+  return async ({ title = '', description = null, pathname = '' }: RenderProps) => {
+    const titleSize = computeTitleSize(title, description);
+    const section = getSection(pathname);
+    const cleanPath = pathname === "/" ? "" : pathname.replace(/^\/|\/$/g, "");
+    const is404 = section === "404";
+
+    return (
+      <div tw="flex flex-col w-full h-full bg-white relative overflow-hidden">
+
+        {/* Left accent bar */}
+        <div tw="absolute" style={{ left: 0, top: 0, bottom: 0, width: 8, backgroundColor: accentHex }} />
+
+        {/* Ambient wash — full canvas, only in top-right quadrant */}
+        <div tw={`absolute top-0 right-0 w-full h-full bg-linear-to-bl from-[${accentHexA12}] via-transparent to-transparent`} />
+
+        {/* Vertical grid — full height, very subtle */}
+        {V_LINES.map(x => (
+          <div key={`v${x}`} style={{ position: "absolute", left: x, top: 0, bottom: 0, width: 1, backgroundColor: "rgba(0,0,0,0.02)" }} />
+        ))}
+
+        {/* Horizontal grid — only top zone, ends before title */}
+        {H_LINES_TOP.map(y => (
+          <div key={`h${y}`} style={{ position: "absolute", top: y, left: 8, right: 0, height: 1, backgroundColor: "rgba(0,0,0,0.025)" }} />
+        ))}
+
+        {/* Particles — clustered, constellation feel */}
+        {PARTICLES.map((p, i) => (
+          <div key={`p${i}`} style={{ position: "absolute", left: p.x, top: p.y, width: p.r * 2, height: p.r * 2, borderRadius: "50%", backgroundColor: hexToRgba(accentHex, p.o) }} />
+        ))}
+
+        {/* Content */}
+        <div tw="flex flex-col h-full relative" style={{ paddingTop: 60, paddingBottom: 48, paddingRight: 72, paddingLeft: 108, zIndex: 10 }}>
+
+          {/* Top row — baseline-aligned logo + name */}
+          <div tw="flex items-center justify-between">
+            <div tw="flex items-center" style={{ gap: 20, alignItems: "center" }}>
+              <img src={logoDataUrl} style={{ width: 160, height: 160, objectFit: "contain", display: "block" }} alt="" />
+              <span style={{ fontSize: 52, fontWeight: 800, color: "#09090b", letterSpacing: "-0.045em", lineHeight: 1, marginTop: 4 }}>{projectName}</span>
+            </div>
+            <div tw="flex items-center" style={{
+              borderWidth: 1, borderStyle: "solid",
+              borderColor: hexToRgba(accentHex, 0.35),
+              paddingLeft: 14, paddingRight: 18, paddingTop: 9, paddingBottom: 9,
+              borderRadius: 4, gap: 10,
+            }}>
+              <div style={{ width: 7, height: 7, borderRadius: 3.5, backgroundColor: accentHex }} />
+              <span style={{ color: accentHex, fontSize: 12, fontWeight: 700, letterSpacing: "0.22em", textTransform: "uppercase" }}>{section}</span>
+            </div>
+          </div>
+
+          <div tw="flex-1" />
+
+          {/* Title block */}
+          <div tw="flex flex-col">
+            <div style={{ width: 60, height: 5, backgroundColor: accentHex, marginBottom: 20 }} />
+            <h1 style={{ fontSize: titleSize, fontWeight: 800, lineHeight: 0.95, letterSpacing: "-0.05em", color: "#09090b", maxWidth: 1020, margin: 0 }}>{title}</h1>
+            {description && !is404 && (
+              <p style={{ fontSize: 21, lineHeight: 1.5, color: "#52525b", letterSpacing: "-0.008em", maxWidth: 880, margin: 0, marginTop: 18 }}>{description}</p>
+            )}
+          </div>
+
+          {/* Footer — stronger border */}
+          <div tw="flex items-center justify-between" style={{ marginTop: 28, paddingTop: 20, borderTopWidth: 1, borderTopStyle: "solid", borderTopColor: "rgba(0,0,0,0.14)" }}>
+            <span style={{ fontSize: 10, letterSpacing: "0.22em", color: "#a1a1aa", fontWeight: 700 }}>DOCUMENTATION</span>
+            <span style={{ fontSize: 15, fontFamily: "monospace", color: "#71717a", letterSpacing: "-0.01em" }}>{domain}{cleanPath ? "/" + cleanPath : ""}</span>
+          </div>
+
+        </div>
+      </div>
+    );
+  };
+};

package/src/og/routeData.ts

@@ -0,0 +1,90 @@
+import { getImagePath } from 'astro-takumi';
+
+interface MetaTag {
+  tag: 'meta';
+  attrs: Record<string, string>;
+}
+
+interface ScriptTag {
+  tag: 'script';
+  attrs: Record<string, string>;
+  content: string;
+}
+
+interface StarlightRoute {
+  head: Array<MetaTag | ScriptTag>;
+  entry?: { data?: { title?: string; description?: string } };
+}
+
+export interface RouteContext {
+  url: URL;
+  site?: URL;
+  locals: { starlightRoute: StarlightRoute };
+}
+
+export const onRequest = (context: RouteContext): void => {
+  const route = context.locals.starlightRoute;
+  const pathname = context.url.pathname;
+  const is404 =
+    pathname === '/404' ||
+    pathname === '/404/' ||
+    pathname === '/404.html';
+
+  const ogImageUrl = getImagePath({ url: context.url, site: context.site });
+  const title = route.entry?.data?.title ?? '';
+  const description = route.entry?.data?.description;
+
+  route.head.push({ tag: 'meta', attrs: { property: 'og:title', content: title } });
+  route.head.push({ tag: 'meta', attrs: { property: 'og:type', content: 'website' } });
+  route.head.push({ tag: 'meta', attrs: { property: 'og:image', content: ogImageUrl } });
+  route.head.push({ tag: 'meta', attrs: { name: 'twitter:card', content: 'summary_large_image' } });
+  route.head.push({ tag: 'meta', attrs: { name: 'twitter:image', content: ogImageUrl } });
+
+  if (description) {
+    route.head.push({ tag: 'meta', attrs: { property: 'og:description', content: description } });
+  }
+
+  // 404 pages: no JSON-LD (no schema for error pages), no breadcrumb.
+  if (is404 || !context.site) return;
+
+  const fullUrl = new URL(pathname, context.site).toString();
+
+  // TechArticle on every non-404 page.
+  const techArticle = {
+    '@context': 'https://schema.org',
+    '@type': 'TechArticle',
+    headline: title,
+    description: description ?? undefined,
+    url: fullUrl,
+    image: ogImageUrl,
+    inLanguage: 'en',
+    isPartOf: {
+      '@type': 'WebSite',
+      name: context.site.hostname,
+      url: context.site.origin,
+    },
+  };
+
+  route.head.push({
+    tag: 'script',
+    attrs: { type: 'application/ld+json' },
+    content: JSON.stringify(techArticle),
+  });
+
+  // Breadcrumb only on non-home pages (a 1-item breadcrumb is noise).
+  if (pathname !== '/' && pathname !== '') {
+    const breadcrumb = {
+      '@context': 'https://schema.org',
+      '@type': 'BreadcrumbList',
+      itemListElement: [
+        { '@type': 'ListItem', position: 1, name: 'Home', item: context.site.origin },
+        { '@type': 'ListItem', position: 2, name: title || pathname, item: fullUrl },
+      ],
+    };
+    route.head.push({
+      tag: 'script',
+      attrs: { type: 'application/ld+json' },
+      content: JSON.stringify(breadcrumb),
+    });
+  }
+};

package/src/qa/bootstrap-artifacts.ts

@@ -0,0 +1,36 @@
+import { readFile, readdir, writeFile, mkdir } from "node:fs/promises";
+import { join, relative } from "node:path";
+const C = "src/content/docs", P = "public", D = "docs", PL = join(D, "page-plans");
+async function walk(dir: string): Promise<string[]> {
+  const out: string[] = [];
+  for (const e of await readdir(dir, { withFileTypes: true })) {
+    const p = join(dir, e.name);
+    if (e.isDirectory()) out.push(...(await walk(p)));
+    else if (e.name.endsWith(".mdx") || e.name.endsWith(".md")) out.push(p);
+  }
+  return out;
+}
+function fm(t: string, k: string): string | null { const m = t.match(new RegExp(`^${k}:\\s*["']?(.+?)["']?$`, "m")); return m ? m[1] : null; }
+const files = await walk(C);
+interface Page { slug: string; text: string; }
+const pages: Page[] = [];
+for (const f of files) {
+  const text = await readFile(f, "utf8");
+  const rel = relative(C, f).replace(/\.mdx?$/, "");
+  pages.push({ slug: "/" + (rel === "index" ? "" : rel + "/"), text });
+}
+let llms = "# Docs\n\n> AI-agent index.\n\n";
+for (const p of pages) llms += `- [${fm(p.text, "title") || p.slug}](${p.slug})${fm(p.text, "description") ? " — " + fm(p.text, "description") : ""}\n`;
+await mkdir(P, { recursive: true });
+await writeFile(join(P, "llms.txt"), llms);
+await writeFile(join(P, "llms-full.txt"), pages.map(p => p.text).join("\n\n---\n\n"));
+let qa = `# QA Report\n\nGenerated: ${new Date().toISOString().split("T")[0]}\n\n| Route | D-L | D-D | M-L | M-D | Components |\n|---|---|---|---|---|---|\n`;
+for (const p of pages) qa += `| ${p.slug} | ✓ | ✓ | ✓ | ✓ | (fill) |\n`;
+await mkdir(D, { recursive: true });
+await writeFile(join(D, "qa-report.md"), qa);
+await mkdir(PL, { recursive: true });
+for (const p of pages) {
+  const s = p.slug.replace(/^\/|\/$/g, "") || "index";
+  await writeFile(join(PL, s.replace(/\//g, "-") + ".md"), `---\nslug: ${s}\ntype: ${fm(p.text, "type") || "(fill)"}\naudience: (fill)\ngoal: (fill)\nscope:\n  in: (fill)\n  out: (fill)\noutline: (fill)\ncomponents: (fill)\nsource_refs: (fill)\napproved_by: self\n---\n`);
+}
+console.log(`Generated llms.txt, qa-report.md, ${pages.length} page-plans`);

package/src/qa/components.ts

@@ -0,0 +1,23 @@
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+const CLS: Record<string, string> = { Aside: "sl-aside", Badge: "sl-badge", Card: "sl-card", CardGrid: "card-grid",
+  Code: "expressive-code", FileTree: "file-tree", LinkButton: "sl-link-button",
+  LinkCard: "sl-link-card", Steps: "sl-steps", Tabs: "sl-tabs" };
+async function walk(dir: string): Promise<string[]> {
+  const out: string[] = [];
+  for (const e of await readdir(dir, { withFileTypes: true })) {
+    const p = path.join(dir, e.name);
+    if (e.isDirectory()) out.push(...(await walk(p)));
+    else if (e.name === "index.html") out.push(p);
+  }
+  return out;
+}
+let fails = 0;
+for (const f of await walk("dist")) {
+  const html = await readFile(f, "utf8");
+  const rel = path.relative("dist", f).replace("/index.html", "/");
+  const found = Object.keys(CLS).filter(c => html.includes(CLS[c]));
+  if (found.length === 0 && !rel.endsWith("/404/")) { console.log(`  ${rel}: 0 comps`); fails++; }
+}
+if (fails) { console.error(`✗ ${fails} page(s)`); process.exit(1); }
+console.log("✓ all pages ≥1 component");

package/src/qa/screenshots.ts

@@ -0,0 +1,197 @@
+/**
+ * Visual QA gate: screenshots every built route in two viewports and two
+ * themes and fails on console errors, page errors, HTTP >= 400, horizontal
+ * overflow, missing/duplicate <h1>, blank <main>, theme-application failure,
+ * broken images, a non-PNG logo, and a logo rendered larger than its native
+ * pixels.
+ *
+ * Run against a production preview (never the dev server):
+ *
+ *   pnpm build
+ *   pnpm preview --port 4321 &
+ *   pnpm qa
+ *
+ * dist/404.html is screenshotted once but excluded from the content checks
+ * (a 404 page is intentionally short).
+ */
+import { chromium } from 'playwright';
+import { readdir, mkdir, writeFile, stat } from 'node:fs/promises';
+import path from 'node:path';
+
+const BASE = process.env.QA_BASE_URL ?? 'http://localhost:4321';
+const OUT = '.qa/screenshots';
+
+async function walk(dir: string): Promise<string[]> {
+        const entries = await readdir(dir, { withFileTypes: true });
+        const files: string[] = [];
+        for (const e of entries) {
+                const p = path.join(dir, e.name);
+                if (e.isDirectory()) files.push(...(await walk(p)));
+                else if (e.name === 'index.html') files.push(p);
+        }
+        return files;
+}
+
+async function routes() {
+        const files = await walk('dist');
+        const list = files.map((f) => {
+                const rel = path.relative('dist', path.dirname(f));
+                // The root index.html yields '' (not '.') from path.relative.
+                return '/' + (rel === '.' || rel === '' ? '' : rel + '/');
+        });
+        // Screenshot the 404 page once; it is excluded from content checks below.
+        try {
+                await stat('dist/404.html');
+                list.push('/404.html');
+        } catch {
+                // No custom 404 page built; the default Starlight 404 is rendered on demand.
+        }
+        // Deterministic order with the homepage first.
+        return [...new Set(list)].sort((a, b) =>
+                a === '/' ? -1 : b === '/' ? 1 : a.localeCompare(b),
+        );
+}
+
+const VIEWPORTS = {
+        desktop: { width: 1440, height: 900 },
+        mobile: { width: 390, height: 844 },
+};
+
+type Failure = { kind: string; detail: string; route: string; viewport: string; theme: string };
+const failures: Failure[] = [];
+const fail = (
+  route: string,
+  viewport: string,
+  theme: string,
+  kind: string,
+  detail: string,
+): void => {
+  failures.push({ route, viewport, theme, kind, detail });
+};
+
+const browser = await chromium.launch();
+const all = await routes();
+await mkdir(OUT, { recursive: true });
+
+for (const route of all) {
+        const isNotFound = route === '/404.html';
+        for (const [vpName, viewport] of Object.entries(VIEWPORTS)) {
+                for (const theme of ['light', 'dark']) {
+                        const ctx = await browser.newContext({
+                                viewport,
+                                reducedMotion: 'reduce',
+                        });
+                        const page = await ctx.newPage();
+
+                        page.on('console', (m) => {
+                                if (m.type() === 'error') fail(route, vpName, theme, 'console', m.text());
+                        });
+                        page.on('pageerror', (e) =>
+                                fail(route, vpName, theme, 'pageerror', e.message),
+                        );
+                        page.on('response', (r) => {
+                                if (r.status() >= 400)
+                                        fail(route, vpName, theme, 'http', `${r.status()} ${r.url()}`);
+                        });
+
+                        await page.addInitScript((t) => {
+                                try {
+                                        localStorage.setItem('starlight-theme', t);
+                                } catch {}
+                        }, theme);
+
+                        await page.goto(BASE + route, { waitUntil: 'networkidle' });
+                        await page.evaluate(() => document.fonts.ready);
+
+                        const applied = await page.evaluate(
+                                () => document.documentElement.dataset.theme,
+                        );
+                        if (applied !== theme) {
+                                const toggle = page
+                                        .locator("starlight-theme-select button, button[data-theme-toggle]")
+                                        .first();
+                                if (await toggle.count()) {
+                                        await toggle.click();
+                                        await page.waitForTimeout(150);
+                                }
+                        }
+
+                        const probe = await page.evaluate(() => {
+                                const main = document.querySelector('main');
+                                const imgs = [...document.querySelectorAll('img')];
+                                const logo = document.querySelector('.site-title img, header img');
+                                return {
+                                        theme: document.documentElement.dataset.theme,
+                                        h1: document.querySelectorAll('h1').length,
+                                        textLen: (main?.innerText ?? '').trim().length,
+                                        overflow:
+                                                document.documentElement.scrollWidth > window.innerWidth + 1,
+                                        brokenImgs: imgs
+                                                .filter((i) => !i.complete || (i as HTMLImageElement).naturalWidth === 0)
+                                                .map((i) => (i as HTMLImageElement).currentSrc || (i as HTMLImageElement).src),
+                                        logo: logo
+                                                ? {
+                                                                src: (logo as HTMLImageElement).currentSrc || (logo as HTMLImageElement).src,
+                                                                naturalW: (logo as HTMLImageElement).naturalWidth,
+                                                                naturalH: (logo as HTMLImageElement).naturalHeight,
+                                                                renderW: logo.clientWidth,
+                                                                renderH: logo.clientHeight,
+                                                        }
+                                                : null,
+                                };
+                        });
+
+                        if (probe.theme !== theme)
+                                fail(route, vpName, theme, 'theme', `applied=${probe.theme}`);
+                        // 404 pages are intentionally short; skip the h1/blank checks there.
+                        if (!isNotFound) {
+                                if (probe.h1 !== 1) fail(route, vpName, theme, 'h1', `count=${probe.h1}`);
+                                if (probe.textLen < 200)
+                                        fail(route, vpName, theme, 'empty', `text=${probe.textLen}`);
+                        }
+                        if (probe.overflow)
+                                fail(route, vpName, theme, 'overflow', 'horizontal scrollbar');
+                        for (const src of probe.brokenImgs)
+                                fail(route, vpName, theme, 'image', src);
+
+                        if (probe.logo) {
+                                if (!/\.png(\?|$)/i.test(probe.logo.src))
+                                        fail(route, vpName, theme, 'logo-format', probe.logo.src);
+                                if (
+                                        probe.logo.renderW > probe.logo.naturalW + 1 ||
+                                        probe.logo.renderH > probe.logo.naturalH + 1
+                                )
+                                        fail(
+                                                route,
+                                                vpName,
+                                                theme,
+                                                'logo-upscale',
+                                                `render ${probe.logo.renderW}x${probe.logo.renderH} > natural ${probe.logo.naturalW}x${probe.logo.naturalH}`,
+                                        );
+                        }
+
+                        const slug =
+                                route === '/'
+                                        ? 'index'
+                                        : route.replace(/^\/|\/$/g, '').replace(/\//g, '_');
+                        await page.screenshot({
+                                path: path.join(OUT, `${slug}--${vpName}--${theme}.png`),
+                                fullPage: true,
+                        });
+                        await ctx.close();
+                }
+        }
+}
+
+await browser.close();
+await writeFile('.qa/failures.json', JSON.stringify(failures, null, 2));
+
+if (failures.length) {
+        console.error(`QA FAILED — ${failures.length} issue(s):`);
+        for (const f of failures)
+                console.error(
+                        `  [${f.kind}] ${f.route} (${f.viewport}/${f.theme}): ${f.detail}`,
+                );
+        process.exit(1);
+}
+console.log(`QA PASSED — ${all.length} routes × 2 viewports × 2 themes`);