@terra-symposium/docs 0.2.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@terra-symposium/docs",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Docs workspace and Markdown site generator.",
   "repository": {
     "type": "git",
@@ -16,6 +16,7 @@
     "bin",
     "site",
     "src/components/navigation.tsx",
+    "src/components/quiz-demo-fixture.ts",
     "src/components/SiteLayout.astro",
     "src/components/NotFound.astro",
     "src/components/NotFound.tsx"
@@ -35,11 +36,7 @@
       "import": "./dist/lib/components/LocalDocsWorkspace.js"
     },
     "./site-layout.astro": "./src/components/SiteLayout.astro",
-    "./not-found.astro": "./src/components/NotFound.astro",
-    "./skills": {
-      "types": "./site/src/components/SkillsExplorer.tsx",
-      "import": "./site/src/components/SkillsExplorer.tsx"
-    }
+    "./not-found.astro": "./src/components/NotFound.astro"
   },
   "bin": {
     "terra-docs": "bin/terra-docs.mjs"
@@ -47,8 +44,8 @@
   "scripts": {
     "dev": "terra-quality-dev -- vite --host 127.0.0.1 --open",
     "docs:dev": "pnpm build && node bin/terra-docs.mjs dev --title 'Docs'",
-    "docs:build": "pnpm build && node bin/terra-docs.mjs build --title 'Docs'",
-    "docs:preview": "pnpm docs:build && node bin/terra-docs.mjs preview --title 'Docs'",
+    "docs:build": "pnpm build && node bin/terra-docs.mjs build --title 'Docs' --out dist/docs",
+    "docs:preview": "pnpm docs:build && node bin/terra-docs.mjs preview --title 'Docs' --out dist/docs",
     "dev:library": "tsc --watch",
     "prebuild": "pnpm exec terra-quality error-boundaries --all",
     "build": "rm -rf dist/lib && tsc && tailwindcss --postcss tailwind.postcss.config.cjs -c tailwind.docs.config.mjs -i src/styles/style.css -o dist/lib/style.css --minify && tailwindcss --postcss tailwind.postcss.config.cjs -c tailwind.docs.config.mjs -i src/styles/workspace.css -o dist/lib/workspace.css --minify && node scripts/copy-runtime.mjs",
@@ -71,7 +68,6 @@
     "@playwright/test": "^1.64.1",
     "@terra-symposium/standards-quality": "2.1.3",
     "@terra-symposium/standards-reporting": "0.6.2",
-    "@types/katex": "^0.16.8",
     "@types/node": "^24.19.2",
     "@types/react": "19.3.0",
     "@types/react-dom": "19.3.0",
@@ -80,6 +76,7 @@
     "eslint": "10.13.0",
     "globals": "^16.5.0",
     "husky": "^9.1.7",
+    "knip": "^6.44.1",
     "postcss": "8.5.31",
     "postcss-import": "15.1.0",
     "prettier": "3.9.10",
@@ -104,14 +101,13 @@
     "@lexical/rich-text": "^0.35.0",
     "@portabletext/editor": "7.9.0",
     "@radix-ui/react-popover": "^1.1.15",
-    "@radix-ui/react-select": "2.4.1",
     "@terra-symposium/standards-error-boundaries": "0.1.2",
     "@terra-symposium/styling": "0.1.34",
-    "bezier-easing": "2.1.0",
-    "@xstate/react": "6.1.0",
     "@uiw/codemirror-theme-github": "^4.25.9",
+    "@xstate/react": "6.1.0",
     "@xyflow/react": "^12.3.6",
     "astro": "^7.4.2",
+    "bezier-easing": "2.1.0",
     "html-to-image": "1.11.11",
     "jszip": "^3.10.1",
     "katex": "^0.19.1",

package/site/astro.config.mjs

@@ -56,14 +56,14 @@ function astroPackageExportAliases() {
       replacement: resolve(astroPackageRoot, 'dist/runtime/$1'),
     },
     ...Object.keys(astroManifest.exports)
-    .filter((key) => key.startsWith('./') && !key.includes('*'))
-    .map((key) => {
-      const specifier = `astro${key.slice(1)}`;
-      return {
-        find: new RegExp(`^${specifier.replace(/[|\\{}()[\]^$+?.]/g, '\\$&')}$`),
-        replacement: requireFromPackage.resolve(specifier),
-      };
-    }),
+      .filter((key) => key.startsWith('./') && !key.includes('*'))
+      .map((key) => {
+        const specifier = `astro${key.slice(1)}`;
+        return {
+          find: new RegExp(`^${specifier.replace(/[|\\{}()[\]^$+?.]/g, '\\$&')}$`),
+          replacement: requireFromPackage.resolve(specifier),
+        };
+      }),
   ];
 }
 
@@ -119,7 +119,12 @@ function stylingDependencyAliases() {
       : dependencyManifest('@terra-symposium/styling', requireFromProject);
   if (!stylingManifest) return [];
   return Object.keys(stylingManifest.dependencies ?? {})
-    .filter((name) => name !== 'react' && name !== 'react-dom' && (name.includes('react') || ['cmdk', 'vaul'].includes(name)))
+    .filter(
+      (name) =>
+        name !== 'react' &&
+        name !== 'react-dom' &&
+        (name.includes('react') || ['cmdk', 'vaul'].includes(name)),
+    )
     .flatMap((name) => {
       const manifest = dependencyManifest(name, requireFromProject);
       if (!manifest) return [];
@@ -152,19 +157,19 @@ function sharedReactAliases() {
   ];
   return [
     ...specifiers.map((specifier) => {
-    let replacement;
-    try {
-      // Externalized component dependencies resolve React from the consumer's
-      // installation during SSR. Prefer that same copy for bundled imports.
-      replacement = requireFromProject.resolve(specifier);
-    } catch {
-      // Content-only repositories can rely on the React runtime shipped by Docs.
-      replacement = requireFromPackage.resolve(specifier);
-    }
-    return {
-      find: new RegExp(`^${specifier.replace(/[|\\{}()[\]^$+?.]/g, '\\$&')}$`),
-      replacement,
-    };
+      let replacement;
+      try {
+        // Externalized component dependencies resolve React from the consumer's
+        // installation during SSR. Prefer that same copy for bundled imports.
+        replacement = requireFromProject.resolve(specifier);
+      } catch {
+        // Content-only repositories can rely on the React runtime shipped by Docs.
+        replacement = requireFromPackage.resolve(specifier);
+      }
+      return {
+        find: new RegExp(`^${specifier.replace(/[|\\{}()[\]^$+?.]/g, '\\$&')}$`),
+        replacement,
+      };
     }),
     {
       // The Docs editor imports `react-dom/server` for Markdown previews. Its

package/site/docs-content-plugin.mjs

@@ -8,7 +8,10 @@ function publicRoute(file, docsRoot, base) {
     .split(sep)
     .join('/')
     .replace(/\.(?:md|mdx)$/i, '');
-  const route = path.replace(/(?:^|\/)index$/i, '').replace(/^\/+|\/+$/g, '');
+  const route = path
+    .replace(/(?:^|\/)SKILL$/i, '')
+    .replace(/(?:^|\/)index$/i, '')
+    .replace(/^\/+|\/+$/g, '');
   return `${base}${route ? `${route}/` : ''}`;
 }
 

package/site/src/components/DocsSiteSearch.tsx

@@ -7,7 +7,15 @@ IMPORTS
 //////////////////////////////////////////////////*/
 
 // API
-import { useEffect, useMemo, useRef, useState } from 'react';
+import { useEffect, useMemo, useState } from 'react';
+import {
+  CommandDialog,
+  CommandEmpty,
+  CommandGroup,
+  CommandInput,
+  CommandItem,
+  CommandList,
+} from '@terra-symposium/styling/ui';
 
 /*//////////////////////////////////////////////////
 CONFIG
@@ -54,8 +62,6 @@ COMPONENTS
  * @return Search controls, loading and error states, and links to matching pages.
  */
 export function DocsSiteSearch({ base = '/' }: Props) {
-  const dialog = useRef<HTMLDialogElement>(null);
-  const input = useRef<HTMLInputElement>(null);
   const [query, setQuery] = useState('');
   const [documents, setDocuments] = useState<SearchDocument[]>([]);
   const [loaded, setLoaded] = useState(false);
@@ -68,9 +74,7 @@ export function DocsSiteSearch({ base = '/' }: Props) {
    * @return Nothing; the callback updates dialog state and browser focus.
    */
   const open = () => {
-    if (!dialog.current?.open) dialog.current?.showModal();
     setOpened(true);
-    window.setTimeout(() => input.current?.focus(), 0);
   };
   useEffect(() => {
     /**
@@ -137,35 +141,49 @@ export function DocsSiteSearch({ base = '/' }: Props) {
       .slice(0, 10);
   }, [documents, query]);
   return (
-    <div className="terra-docs-search">
-      <dialog className="terra-docs-search-dialog" ref={dialog} onClose={() => setQuery('')}>
-        <div className="terra-docs-search-panel">
-          <label className="terra-docs-search-input-row">
-            <span aria-hidden="true">⌕</span>
-            <input
-              ref={input}
-              value={query}
-              onChange={(event) => setQuery(event.currentTarget.value)}
-              placeholder="Search documentation…"
-            />
-            <button type="button" onClick={() => dialog.current?.close()} aria-label="Close search">
-              Esc
-            </button>
-          </label>
-          <div className="terra-docs-search-results" aria-live="polite">
-            {failed ? <p>Search is unavailable right now.</p> : null}
-            {!loaded && !failed ? <p>Loading search…</p> : null}
-            {loaded && query.trim() && results.length === 0 ? <p>No matching pages.</p> : null}
+    <CommandDialog
+      open={opened}
+      onOpenChange={(nextOpen) => {
+        setOpened(nextOpen);
+        if (!nextOpen) setQuery('');
+      }}
+      size="lg"
+      className="max-w-2xl"
+      aria-label="Search documentation"
+    >
+      <CommandInput value={query} onValueChange={setQuery} placeholder="Search documentation…" />
+      <CommandList className="max-h-[min(60vh,32rem)] p-2">
+        {failed ? <CommandEmpty>Search is unavailable right now.</CommandEmpty> : null}
+        {!loaded && !failed ? <CommandEmpty>Loading search…</CommandEmpty> : null}
+        {loaded && query.trim() && results.length === 0 ? (
+          <CommandEmpty>No matching pages.</CommandEmpty>
+        ) : null}
+        {results.length > 0 ? (
+          <CommandGroup>
             {results.map(({ document }) => (
-              <a key={document.href} href={document.href} onClick={() => dialog.current?.close()}>
-                <strong>{document.title}</strong>
-                {document.description ? <span>{document.description}</span> : null}
-                <small>{excerpt(document.text, query.trim().split(S_REGEX)[0] ?? query)}</small>
-              </a>
+              <CommandItem
+                key={document.href}
+                value={`${document.title} ${document.description} ${document.text}`}
+                onSelect={() => {
+                  window.location.assign(document.href);
+                  setOpened(false);
+                }}
+                className="items-start py-3"
+              >
+                <span className="flex min-w-0 flex-col gap-1">
+                  <strong>{document.title}</strong>
+                  {document.description ? (
+                    <span className="text-sm text-primary-11">{document.description}</span>
+                  ) : null}
+                  <small className="line-clamp-2 text-xs text-primary-10">
+                    {excerpt(document.text, query.trim().split(S_REGEX)[0] ?? query)}
+                  </small>
+                </span>
+              </CommandItem>
             ))}
-          </div>
-        </div>
-      </dialog>
-    </div>
+          </CommandGroup>
+        ) : null}
+      </CommandList>
+    </CommandDialog>
   );
 }

package/site/src/components/QuizDemo.tsx

@@ -0,0 +1,62 @@
+import { DocsSiteIsland } from './DocsSiteIsland.js';
+import type { DocsSection } from '../../../dist/lib/lib/workspace-types.js';
+import type { DocsQuizConfig, DocsQuizGenerationInput } from '../../../dist/lib/components/quiz.js';
+import { quizDemoLeaf, quizDemoResponse } from '../../../src/components/quiz-demo-fixture.js';
+
+const markdown = quizDemoLeaf.markdown;
+const visibleLeafText = markdown.split('\n\n', 1)[0] ?? markdown;
+
+const sections: DocsSection[] = [
+  {
+    id: 'course',
+    title: 'Course',
+    groups: [
+      {
+        id: 'lessons',
+        title: 'Lessons',
+        leaves: [
+          {
+            id: quizDemoLeaf.id,
+            title: quizDemoLeaf.title,
+            href: '/quiz-demo/',
+            description: 'The routing leaf shared with the quiz browser tests.',
+          },
+        ],
+      },
+    ],
+  },
+];
+
+function genDemoQuiz(input: DocsQuizGenerationInput): Promise<unknown> {
+  return Promise.resolve({
+    title: `${quizDemoResponse.title} · sample`,
+    questions: Array.from({ length: input.count }, (_, i) => {
+      const type = input.types[i % input.types.length];
+      const question =
+        quizDemoResponse.questions.find((candidate) => candidate.type === type) ??
+        quizDemoResponse.questions[0];
+      return { ...question };
+    }),
+  });
+}
+
+const quiz: DocsQuizConfig = { toolbar: true, generate: genDemoQuiz };
+
+/** A package-safe interactive demo for the host-configurable leaf quiz flow. */
+export function QuizDemo() {
+  return (
+    <DocsSiteIsland
+      title="Docs quiz demo"
+      description="The published Docs workspace with sample leaf quiz generation."
+      hue={145}
+      sections={sections}
+      currentPath="/quiz-demo/"
+      rootPath="/quiz-demo/"
+      staticContent
+      markdown={markdown}
+      renderContent={<p className="leading-7">{visibleLeafText}</p>}
+      quiz={quiz}
+      searchBase="/"
+    />
+  );
+}

package/site/src/lib/catalog.ts

@@ -72,10 +72,17 @@ const sources = import.meta.glob<string>('/docs/**/*.{md,mdx}', {
   eager: true,
 });
 const base = import.meta.env.BASE_URL;
+const includeAgents = import.meta.env.PUBLIC_TERRA_DOCS_INCLUDE_AGENTS !== 'false';
 const routes = new Map<string, string>();
 /** Visible Docs pages sorted by configured sidebar order and source path. */
 export const sitePages: SitePage[] = Object.entries(modules)
+  .filter(([file]) => includeAgents || !file.startsWith('/docs/agents/'))
   .map(([file, module]) => {
+    const relativeFile = file.replace(/^\/docs\//, '');
+    const isRootIndex = ['index.md', 'index.mdx'].includes(relativeFile.toLowerCase());
+    if (!isRootIndex && !relativeFile.includes('/')) {
+      throw new Error(`Markdown pages must be grouped in folders directly under docs/: ${file}`);
+    }
     const slug = routeForFile(file);
     const previous = routes.get(slug);
     if (previous) throw new Error(`Duplicate Docs route "${slug || '/'}": ${previous} and ${file}`);
@@ -131,7 +138,10 @@ function titleFromSource(source: string, slug: string): string {
  */
 function routeForFile(file: string): string {
   const relative = file.replace(/^\/?docs\//, '').replace(/\.(?:md|mdx)$/i, '');
-  return relative.replace(/(?:^|\/)index$/i, '').replace(G_CLASS_2(), '');
+  return relative
+    .replace(/(?:^|\/)SKILL$/i, '')
+    .replace(/(?:^|\/)index$/i, '')
+    .replace(G_CLASS_2(), '');
 }
 
 /**
@@ -201,9 +211,7 @@ export function pageForSlug(slug: string): SitePage | undefined {
   return sitePages.find((page) => page.slug === slug);
 }
 if (sitePages.length === 0)
-  throw new Error(
-    'No Markdown files found in docs/. Add docs/index.md to start a Docs site.',
-  );
+  throw new Error('No Markdown files found in docs/. Add docs/index.md to start a Docs site.');
 for (const page of sitePages.filter((i) => !i.hidden && i.slug !== '404')) {
   const segments = page.slug.split('/').filter(Boolean);
   let currentNodes = rootNodes;

package/site/src/pages/[...slug].astro

@@ -15,11 +15,10 @@ export function getStaticPaths() {
 
 const { slug = '' } = Astro.props;
 const page = pageForSlug(slug);
-const PageContent = page?.content;
 const currentPath = pageHref(slug, base);
 ---
 
-{page && PageContent ? (
+{page ? (
 	<html lang="en">
 		<head>
 			<meta charset="utf-8" />
@@ -37,14 +36,9 @@ const currentPath = pageHref(slug, base);
 				nodes={siteNavigation}
 				currentPath={currentPath}
 				rootPath={pageHref('', base)}
+				markdown={page.markdown}
 				searchBase={base}
-			>
-				<div class="terra-docs-page-content"><PageContent /></div>
-			</DocsSiteLayout>
+			/>
 		</body>
 	</html>
 ) : null}
-
-<style is:global>
-	.terra-docs-page-content { max-width: 100%; }
-</style>

package/site/src/pages/quiz-demo.astro

@@ -0,0 +1,50 @@
+---
+import { QuizDemo } from '../components/QuizDemo.js';
+import '@terra-symposium/docs/style.css';
+---
+<!doctype html>
+<html lang="en" class="light">
+	<head>
+		<meta charset="utf-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1" />
+		<meta name="description" content="Try the shared Docs leaf quiz flow with the Playwright workspace fixture." />
+		<title>Leaf quiz demo · Docs</title>
+	</head>
+	<body>
+		<header class="demo-intro">
+			<p>Docs component demo</p>
+			<h1>Generate a quiz from a leaf</h1>
+			<p>Select a leaf, then choose <strong>Generate quiz</strong>. This fixture returns clearly marked sample questions and never sends content to an AI service.</p>
+		</header>
+		<QuizDemo client:load />
+	</body>
+</html>
+
+<style>
+	.demo-intro {
+		margin-left: 22rem;
+		padding: 1.25rem clamp(1rem, 4vw, 3rem);
+		background: #f7f4fb;
+		color: #24172f;
+	}
+	.demo-intro > p:first-child {
+		margin: 0 0 0.35rem;
+		font-size: 0.75rem;
+		font-weight: 700;
+		letter-spacing: 0.08em;
+		text-transform: uppercase;
+	}
+	.demo-intro h1 {
+		margin: 0;
+		font-size: clamp(1.25rem, 2.5vw, 1.8rem);
+	}
+	.demo-intro > p:last-child {
+		margin: 0.35rem 0 0;
+		font-size: 0.9rem;
+	}
+	@media (max-width: 767px) {
+		.demo-intro {
+			margin-left: 0;
+		}
+	}
+</style>

package/src/components/navigation.tsx

@@ -27,8 +27,8 @@ export function DocsNavigation({
   const style = { '--docs-accent': `rgb(${accent.light[8]})` } as CSSProperties;
   const render = (items: DocsNavNode[]): JSX.Element => (
     <ul className="terra-docs-nav-list">
-      {items.map((node, index) => (
-        <li key={`${node.href ?? node.title}-${index}`}>
+      {items.map((node, i) => (
+        <li key={`${node.href ?? node.title}-${i}`}>
           {node.href ? (
             <a href={node.href} aria-current={node.href === currentPath ? 'page' : undefined}>
               {node.title}

package/src/components/quiz-demo-fixture.ts

@@ -0,0 +1,23 @@
+/** Shared quiz leaf data used by the public demo and its Playwright fixture. */
+export const quizDemoLeaf = {
+  id: 'quiz-leaf',
+  path: 'content/course/quiz-leaf/index.md',
+  title: 'Course Leaf',
+  markdown:
+    'Leaf source: routing sends packets between networks.\n\n:::terra-docs quiz\n_type: quiz\n:::',
+};
+
+/** Stable sample response for review, run, and score coverage. */
+export const quizDemoResponse = {
+  title: 'Routing quiz',
+  questions: [
+    {
+      type: 'multipleChoice',
+      prompt: 'What does a router do?',
+      opts: ['Routes packets', 'Stores files'],
+      answer: 'Routes packets',
+      explanation: 'It forwards packets between networks.',
+    },
+    { type: 'keyword', prompt: 'What does it forward?', answers: ['packets'] },
+  ],
+} as const;