@terra-symposium/docs 0.1.77 → 0.1.78

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@terra-symposium/docs",
-  "version": "0.1.77",
+  "version": "0.1.78",
   "description": "Terra Docs workspace and Markdown site generator.",
   "repository": {
     "type": "git",
@@ -50,6 +50,7 @@
     "docs:build": "pnpm build && node bin/terra-docs.mjs build --title 'Terra Docs'",
     "docs:preview": "pnpm docs:build && node bin/terra-docs.mjs preview --title 'Terra Docs'",
     "dev:library": "tsc --watch",
+    "prebuild": "pnpm exec terra-quality error-boundaries --all",
     "build": "rm -rf lib-dist && tsc && tailwindcss --postcss tailwind.postcss.config.cjs -c tailwind.docs.config.mjs -i src/styles/style.css -o lib-dist/style.css --minify && tailwindcss --postcss tailwind.postcss.config.cjs -c tailwind.docs.config.mjs -i src/styles/workspace.css -o lib-dist/workspace.css --minify && node scripts/copy-runtime.mjs",
     "build:demo": "vite build",
     "typecheck": "tsc --noEmit && tsc -p tsconfig.demo.json",
@@ -104,7 +105,10 @@
     "@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",
     "@xyflow/react": "^12.3.6",
     "astro": "^7.4.2",
@@ -118,6 +122,7 @@
     "react-dom": "^19.3.1",
     "sanitize-html": "^2.18.1",
     "sonner": "^1.4.41",
+    "use-sync-external-store": "1.7.0",
     "yaml": "^2.7.0"
   },
   "license": "Apache-2.0"

package/site/astro.config.mjs

@@ -1,3 +1,4 @@
+import { terraErrorBoundaryIntegration as __terraErrorBoundaryIntegration } from '@terra-symposium/standards-error-boundaries/astro-integration';
 import { fileURLToPath } from 'node:url';
 import { resolve } from 'node:path';
 import { readFileSync } from 'node:fs';
@@ -12,6 +13,9 @@ import { docsContentPlugin } from './docs-content-plugin.mjs';
 
 const packageRoot = fileURLToPath(new URL('../', import.meta.url));
 const requireFromPackage = createRequire(import.meta.url);
+const stylingEntry = requireFromPackage.resolve('@terra-symposium/styling');
+const requireFromStyling = createRequire(stylingEntry);
+const docsManifest = JSON.parse(readFileSync(resolve(packageRoot, 'package.json'), 'utf8'));
 const projectRoot = process.env.TERRA_DOCS_ROOT ?? process.cwd();
 const publicDir = resolve(projectRoot, '.terra-docs/public');
 const outDir = resolve(projectRoot, process.env.TERRA_DOCS_OUT ?? 'dist/docs');
@@ -42,19 +46,6 @@ function packageExportAliases() {
   });
 }
 
-const packageDependencyResolver = {
-  name: 'terra-docs-package-dependencies',
-  enforce: 'pre',
-  resolveId(source) {
-    if (!/^(?:astro|@astrojs\/(?:markdown-remark|mdx|react))(?:\/|$)/.test(source)) return null;
-    try {
-      return requireFromPackage.resolve(source);
-    } catch {
-      return null;
-    }
-  },
-};
-
 export default defineConfig({
   root: projectRoot,
   srcDir: resolve(packageRoot, 'site/src'),
@@ -64,12 +55,15 @@ export default defineConfig({
   base,
   devToolbar: { enabled: false },
   build: { format: 'directory' },
-  integrations: [react({ experimentalDisableStreaming: true }), mdx()],
+  integrations: [__terraErrorBoundaryIntegration(), react(), mdx()],
   markdown: { processor: unified({ remarkPlugins: [[basePathRemarkPlugin, { base }]] }) },
   vite: {
-    plugins: [packageDependencyResolver, docsContentPlugin({ root: projectRoot, base })],
+    plugins: [docsContentPlugin({ root: projectRoot, base })],
     optimizeDeps: { include: [...DOCS_VITE_OPTIMIZE_DEPS] },
-    resolve: { alias: packageExportAliases() },
+    resolve: {
+      alias: packageExportAliases(),
+      dedupe: ['react', 'react-dom'],
+    },
     server: { fs: { allow: [projectRoot, packageRoot] } },
   },
 });

package/site/src/components/DocsSiteIsland.tsx

@@ -0,0 +1,76 @@
+/**
+ * site/src/components/DocsSiteIsland.tsx
+ */
+
+/*//////////////////////////////////////////////////
+IMPORTS
+//////////////////////////////////////////////////*/
+
+// COMPONENTS
+import React from 'react';
+import { ErrorBoundary } from '@terra-symposium/standards-error-boundaries/react';
+
+// TYPES
+import type { ComponentProps } from 'react';
+
+/*//////////////////////////////////////////////////
+CONFIG
+//////////////////////////////////////////////////*/
+
+const { lazy, Suspense } = React;
+const DocsStaticWorkspace = lazy(() =>
+  import('../../../lib-dist/components/StaticWorkspace.js').then(({ DocsStaticWorkspace }) => ({
+    default: DocsStaticWorkspace,
+  })),
+);
+const DocsSiteSearch = lazy(() =>
+  import('./DocsSiteSearch.js').then(({ DocsSiteSearch }) => ({ default: DocsSiteSearch })),
+);
+type Props = ComponentProps<typeof DocsStaticWorkspace> & { searchBase?: string };
+
+/*//////////////////////////////////////////////////
+COMPONENTS
+//////////////////////////////////////////////////*/
+
+/**
+ * Keeps Docs workspace and search rendering failures inside a visible, recoverable page boundary.
+ *
+ * @param props Workspace data and the base path used for search-index requests.
+ *
+ * @return The lazy Docs workspace and search dialog inside a recoverable error boundary.
+ */
+export function DocsSiteIsland({ searchBase = '/', ...workspaceProps }: Props) {
+  return (
+    <ErrorBoundary
+      name="Docs site"
+      onError={(error, report) => console.error(`[${report.name}]`, error, report.componentStack)}
+      fallback={() => (
+        <main
+          aria-labelledby="docs-site-error-title"
+          className="mx-auto my-12 max-w-2xl p-6"
+          role="alert"
+        >
+          <h1 id="docs-site-error-title">Documentation could not load</h1>
+          <p>
+            The Docs interface encountered a rendering error. The rest of this page remains
+            available.
+          </p>
+          <button onClick={() => window.location.reload()} type="button">
+            Reload Docs
+          </button>
+        </main>
+      )}
+    >
+      <Suspense
+        fallback={
+          <p aria-live="polite" role="status">
+            Loading documentation…
+          </p>
+        }
+      >
+        <DocsStaticWorkspace {...workspaceProps} />
+        <DocsSiteSearch base={searchBase} />
+      </Suspense>
+    </ErrorBoundary>
+  );
+}

package/site/src/components/DocsSiteSearch.tsx

@@ -1,22 +1,58 @@
+/**
+ * site/src/components/DocsSiteSearch.tsx
+ */
+
+/*//////////////////////////////////////////////////
+IMPORTS
+//////////////////////////////////////////////////*/
+
+// API
 import { useEffect, useMemo, useRef, useState } from 'react';
 
+/*//////////////////////////////////////////////////
+CONFIG
+//////////////////////////////////////////////////*/
+
+const S_REGEX = /\s+/;
 type SearchDocument = {
   title: string;
   description: string;
   href: string;
   text: string;
 };
-
 type Props = { base?: string };
 
+/*//////////////////////////////////////////////////
+HELPERS
+//////////////////////////////////////////////////*/
+
+/**
+ * Builds a short search snippet around the first matching query term.
+ *
+ * @param text Document text to show in the result.
+ * @param query Term used to locate the most relevant excerpt position.
+ *
+ * @return A clipped excerpt with ellipses where surrounding text was omitted.
+ */
 function excerpt(text: string, query: string): string {
-  const normalized = text.replace(/\s+/g, ' ').trim();
-  const offset = normalized.toLowerCase().indexOf(query.toLowerCase());
+  const norm = text.replace(/\s+/g, ' ').trim();
+  const offset = norm.toLowerCase().indexOf(query.toLowerCase());
   const start = Math.max(0, offset - 72);
-  const end = Math.min(normalized.length, start + 190);
-  return `${start > 0 ? '…' : ''}${normalized.slice(start, end)}${end < normalized.length ? '…' : ''}`;
+  const end = Math.min(norm.length, start + 190);
+  return `${start > 0 ? '…' : ''}${norm.slice(start, end)}${end < norm.length ? '…' : ''}`;
 }
 
+/*//////////////////////////////////////////////////
+COMPONENTS
+//////////////////////////////////////////////////*/
+
+/**
+ * Provides a keyboard-accessible dialog for searching the generated Docs index.
+ *
+ * @param props Optional base path used to fetch the site's search index.
+ *
+ * @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);
@@ -25,16 +61,31 @@ export function DocsSiteSearch({ base = '/' }: Props) {
   const [loaded, setLoaded] = useState(false);
   const [failed, setFailed] = useState(false);
   const [opened, setOpened] = useState(false);
-  const normalizedBase = base.endsWith('/') ? base : `${base}/`;
-
+  const normBase = base.endsWith('/') ? base : `${base}/`;
+  /**
+   * Opens the dialog and moves keyboard focus to the search field.
+   *
+   * @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(() => {
+    /**
+     * Opens search in response to the Docs site's custom search event.
+     *
+     * @return Nothing; the callback delegates to the dialog opener.
+     */
     const onOpenSearch = () => open();
+    /**
+     * Opens search for the supported keyboard shortcuts outside form controls.
+     *
+     * @param event Keyboard event dispatched by the document.
+     *
+     * @return Nothing; a matching shortcut is prevented and opens the dialog.
+     */
     const onKeyDown = (event: KeyboardEvent) => {
       if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === 'k') {
         event.preventDefault();
@@ -54,10 +105,9 @@ export function DocsSiteSearch({ base = '/' }: Props) {
       document.removeEventListener('keydown', onKeyDown);
     };
   }, []);
-
   useEffect(() => {
     if (!opened || loaded) return;
-    fetch(`${normalizedBase}_terra-docs/search-index.json`)
+    fetch(`${normBase}_terra-docs/search-index.json`)
       .then((response) => {
         if (!response.ok) throw new Error(`Search index returned ${response.status}`);
         return response.json() as Promise<SearchDocument[]>;
@@ -67,10 +117,9 @@ export function DocsSiteSearch({ base = '/' }: Props) {
         setLoaded(true);
       })
       .catch(() => setFailed(true));
-  }, [loaded, normalizedBase, opened]);
-
+  }, [loaded, normBase, opened]);
   const results = useMemo(() => {
-    const terms = query.toLowerCase().trim().split(/\s+/).filter(Boolean);
+    const terms = query.toLowerCase().trim().split(S_REGEX).filter(Boolean);
     if (!terms.length) return [];
     return documents
       .map((document) => {
@@ -87,7 +136,6 @@ 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('')}>
@@ -112,7 +160,7 @@ export function DocsSiteSearch({ base = '/' }: Props) {
               <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+/)[0] ?? query)}</small>
+                <small>{excerpt(document.text, query.trim().split(S_REGEX)[0] ?? query)}</small>
               </a>
             ))}
           </div>

package/site/src/components/SkillsExplorer.tsx

@@ -1,6 +1,24 @@
+/**
+ * site/src/components/SkillsExplorer.tsx
+ */
+
+/*//////////////////////////////////////////////////
+IMPORTS
+//////////////////////////////////////////////////*/
+
+// API
 import { useMemo, useState } from 'react';
-import '../styles/skills-explorer.css';
 
+// COMPONENTS
+import { Button, Input, Label } from '@terra-symposium/styling/ui';
+
+/*//////////////////////////////////////////////////
+CONFIG
+//////////////////////////////////////////////////*/
+
+/**
+ * Skill content and metadata prepared for display in the repository skills explorer.
+ */
 export type SkillRecord = {
   body: string;
   description: string;
@@ -13,22 +31,52 @@ export type SkillRecord = {
   title: string;
 };
 
+/*//////////////////////////////////////////////////
+HELPERS
+//////////////////////////////////////////////////*/
+
+/**
+ * Converts scalar metadata to readable text and structured metadata to JSON.
+ *
+ * @param value Metadata value parsed from a skill's YAML frontmatter.
+ *
+ * @return Text suitable for searching and displaying in the explorer.
+ */
 function metadataValue(value: unknown) {
   if (typeof value === 'string') return value;
   if (typeof value === 'number' || typeof value === 'boolean') return String(value);
   return JSON.stringify(value);
 }
 
+/**
+ * Formats a count with a simple English plural suffix.
+ *
+ * @param count Number of matching items.
+ * @param singular Singular label for one item.
+ *
+ * @return The count followed by the singular or plural label.
+ */
 function plural(count: number, singular: string) {
   return `${count} ${singular}${count === 1 ? '' : 's'}`;
 }
 
+/*//////////////////////////////////////////////////
+COMPONENTS
+//////////////////////////////////////////////////*/
+
+/**
+ * Lets readers filter, select, and inspect the repository's indexed skill files.
+ *
+ * @param props Skill records built from the repository's `SKILL.md` files.
+ *
+ * @return A filterable list and the selected skill's description and content.
+ */
 export function SkillsExplorer({ skills }: { skills: SkillRecord[] }) {
   const [query, setQuery] = useState('');
-  const [activePath, setActivePath] = useState(skills[0]?.sourcePath ?? '');
+  const [aPath, setActivePath] = useState(skills[0]?.sourcePath ?? '');
   const filteredSkills = useMemo(() => {
-    const normalizedQuery = query.trim().toLocaleLowerCase();
-    if (!normalizedQuery) return skills;
+    const normQuery = query.trim().toLocaleLowerCase();
+    if (!normQuery) return skills;
     return skills.filter((skill) =>
       [
         skill.name,
@@ -42,11 +90,11 @@ export function SkillsExplorer({ skills }: { skills: SkillRecord[] }) {
       ]
         .join('\n')
         .toLocaleLowerCase()
-        .includes(normalizedQuery),
+        .includes(normQuery),
     );
   }, [query, skills]);
   const selectedSkill =
-    filteredSkills.find((skill) => skill.sourcePath === activePath) ?? filteredSkills[0] ?? null;
+    filteredSkills.find((skill) => skill.sourcePath === aPath) ?? filteredSkills[0] ?? null;
   const groups = useMemo(() => {
     const byScope = new Map<string, SkillRecord[]>();
     for (const skill of filteredSkills) {
@@ -61,93 +109,118 @@ export function SkillsExplorer({ skills }: { skills: SkillRecord[] }) {
         ([key]) => !['name', 'description'].includes(key),
       )
     : [];
-
   return (
-    <section aria-label="Repository skills" className="docs-skills">
-      <header className="docs-skills__header">
+    <section aria-label="Repository skills" className="my-8">
+      <header className="mb-4 flex flex-wrap items-end justify-between gap-6">
         <div>
-          <p className="docs-skills__eyebrow">Repository inventory</p>
-          <h2>Skills</h2>
-          <p>Browse the workflows and guidance files included in this repository.</p>
+          <p className="mb-1 text-xs font-bold uppercase tracking-wider text-gray-10">
+            Repository inventory
+          </p>
+          <h2 className="m-0">Skills</h2>
+          <p className="mb-0 mt-1 text-gray-10">
+            Browse the workflows and guidance files included in this repository.
+          </p>
         </div>
-        <div aria-live="polite" className="docs-skills__summary">
-          <strong>{skills.length}</strong>
+        <div aria-live="polite" className="grid justify-items-end text-sm text-gray-10">
+          <strong className="text-2xl leading-none text-primary-11">{skills.length}</strong>
           <span>{plural(skills.length, 'skill')} indexed</span>
         </div>
       </header>
-
       {skills.length ? (
-        <div className="docs-skills__layout">
-          <nav aria-label="Available skills" className="docs-skills__index">
-            <label className="docs-skills__filter">
-              <span>Filter skills</span>
-              <input
+        <div className="grid min-w-0 items-start gap-4 md:grid-cols-[minmax(16rem,0.8fr)_minmax(0,1.6fr)]">
+          <nav
+            aria-label="Available skills"
+            className="max-h-[78vh] min-w-0 overflow-auto rounded-xl border border-gray-6 bg-gray-1 p-3"
+          >
+            <div>
+              <Label htmlFor="skills-explorer-filter">Filter skills</Label>
+              <Input
+                id="skills-explorer-filter"
                 onChange={(event) => setQuery(event.currentTarget.value)}
                 placeholder="Name, topic, or text"
                 type="search"
                 value={query}
               />
-            </label>
-            <p aria-live="polite" className="docs-skills__count">
+            </div>
+            <p aria-live="polite" className="mb-4 mt-2 text-xs text-gray-10">
               Showing {filteredSkills.length} of {skills.length}
             </p>
             {groups.length ? (
               groups.map(([scope, entries]) => (
-                <section aria-label={scope} className="docs-skills__group" key={scope}>
-                  <h3>{scope}</h3>
-                  <ul>
+                <section aria-label={scope} className="mt-4 first:mt-0" key={scope}>
+                  <h3 className="mb-2 break-words text-xs font-bold uppercase text-gray-10">
+                    {scope}
+                  </h3>
+                  <ul className="m-0 grid list-none gap-1 p-0">
                     {entries.map((skill) => (
                       <li key={skill.sourcePath}>
-                        <button
+                        <Button
                           aria-current={
                             selectedSkill?.sourcePath === skill.sourcePath ? 'true' : undefined
                           }
-                          className="docs-skills__item"
+                          className="h-auto w-full justify-start px-3 py-2 text-left"
                           onClick={() => setActivePath(skill.sourcePath)}
+                          variant={
+                            selectedSkill?.sourcePath === skill.sourcePath
+                              ? 'primary-tonal'
+                              : 'gray-ghost'
+                          }
                           type="button"
                         >
-                          <span className="docs-skills__item-title">{skill.title}</span>
-                          <span className="docs-skills__item-description">
-                            {skill.description || skill.name}
+                          <span className="grid min-w-0 gap-1">
+                            <span className="font-semibold leading-snug">{skill.title}</span>
+                            <span className="line-clamp-2 text-xs font-normal text-gray-10">
+                              {skill.description || skill.name}
+                            </span>
+                            <span className="truncate text-[0.7rem] font-normal text-gray-9">
+                              {skill.directory}
+                            </span>
                           </span>
-                          <span className="docs-skills__item-path">{skill.directory}</span>
-                        </button>
+                        </Button>
                       </li>
                     ))}
                   </ul>
                 </section>
               ))
             ) : (
-              <p className="docs-skills__empty">No skills match “{query}”.</p>
+              <p className="text-sm text-gray-10">No skills match “{query}”.</p>
             )}
           </nav>
-
           {selectedSkill ? (
-            <article aria-live="polite" className="docs-skills__detail">
-              <header>
-                <p className="docs-skills__eyebrow">{selectedSkill.scope}</p>
-                <h3>{selectedSkill.title}</h3>
-                <p className="docs-skills__description">{selectedSkill.description}</p>
-                <p className="docs-skills__source-path">{selectedSkill.sourcePath}</p>
+            <article
+              aria-live="polite"
+              className="min-w-0 overflow-hidden rounded-xl border border-gray-6 bg-gray-1"
+            >
+              <header className="border-b border-gray-6 p-4">
+                <p className="mb-1 text-xs font-bold uppercase tracking-wider text-primary-11">
+                  {selectedSkill.scope}
+                </p>
+                <h3 className="mb-2 mt-0">{selectedSkill.title}</h3>
+                <p className="mb-2 text-gray-10">{selectedSkill.description}</p>
+                <p className="mb-0 break-all font-mono text-xs text-gray-9">
+                  {selectedSkill.sourcePath}
+                </p>
               </header>
               {metadataEntries.length ? (
-                <dl className="docs-skills__metadata">
+                <dl className="m-0 grid gap-3 border-b border-gray-6 p-4 sm:grid-cols-2">
                   {metadataEntries.map(([key, value]) => (
-                    <div key={key}>
-                      <dt>{key.replace(/[-_]+/g, ' ')}</dt>
-                      <dd>{metadataValue(value)}</dd>
+                    <div className="min-w-0" key={key}>
+                      <dt className="text-xs font-semibold uppercase text-gray-10">
+                        {key.replace(/[-_]+/g, ' ')}
+                      </dt>
+                      <dd className="mb-0 mt-1 break-words text-sm">{metadataValue(value)}</dd>
                     </div>
                   ))}
                 </dl>
               ) : null}
               {selectedSkill.metadataIssue ? (
-                <p className="docs-skills__metadata-issue">
+                <p className="m-4 rounded-md border border-gray-6 bg-gray-2 p-3 text-sm">
                   Frontmatter could not be parsed: {selectedSkill.metadataIssue}
                 </p>
               ) : null}
-              <details className="docs-skills__source" open>
-                <summary>Full skill instructions</summary>
-                <pre>
+              <details className="p-4" open>
+                <summary className="cursor-pointer font-semibold">Full skill instructions</summary>
+                <pre className="mt-3 max-h-[60vh] overflow-auto whitespace-pre-wrap break-words rounded-lg bg-gray-2 p-4 text-sm">
                   <code>{selectedSkill.body}</code>
                 </pre>
               </details>
@@ -155,7 +228,7 @@ export function SkillsExplorer({ skills }: { skills: SkillRecord[] }) {
           ) : null}
         </div>
       ) : (
-        <p className="docs-skills__empty">
+        <p className="rounded-lg border border-gray-6 bg-gray-1 p-4 text-sm text-gray-10">
           No SKILL.md files were found in this repository. Add skills under a .agents/skills or
           .codex/skills folder, then rebuild the Docs site.
         </p>
@@ -163,5 +236,4 @@ export function SkillsExplorer({ skills }: { skills: SkillRecord[] }) {
     </section>
   );
 }
-
 export default SkillsExplorer;