fix(website): fit meta descriptions to the search-snippet budget (#880)

GSC follow-up to #826: descriptions over ~160 chars get re-truncated by
Google mid-sentence, and the docs fallback path hard-sliced the first
paragraph at 177 chars mid-word with '...'.

- New clampMetaDescription in site-metadata.ts: ≤160 chars, prefers a
  sentence boundary past 60% of the budget, otherwise cuts at a word
  boundary with a real ellipsis. Applied centrally in createPageMetadata
  and at the docs/blog description sources so each page's JSON-LD stays
  byte-identical to its meta description.
- Docs extracted-paragraph path now uses the clamp (no more mid-word
  '...' cuts on the 111 pages without frontmatter descriptions).
- Rewrote the 5 over-budget blog descriptions and the pricing page
  description by hand so the author-chosen copy fits without clamping.
- Specs: clamp unit tests, a docs sweep (every page ≤160, no legacy
  '...', guarded against an empty slug list), and a real-content blog
  frontmatter gate in site-metadata.spec.ts (blog.spec.ts mocks fs).

The clamp immediately caught the pricing page description losing its
'$29 per developer per month' claim — shortened at the source instead.

nx test green (371 passing), lint 0 errors, production build green.

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

Author: blove

apps/website/content/blog/2026-05-21-build-fullstack-agentic-angular-apps-using-ag-ui.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Build Fullstack Agentic Angular Apps Using AG-UI"
-description: "A practical, signal-native walkthrough for wiring any AG-UI backend (LangGraph, CrewAI, Mastra, Pydantic AI, Microsoft Agent Framework) to a production Angular chat UI."
+description: "A practical walkthrough for wiring any AG-UI backend — LangGraph, CrewAI, Mastra, Pydantic AI, and more — to a production Angular chat UI."
 date: 2026-05-21
 tags: [tutorial, ag-ui, angular, agents, langgraph]
 author: brian

apps/website/content/blog/2026-05-28-human-in-the-loop-langgraph-agents-in-angular.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Human-in-the-Loop LangGraph Agents in Angular"
-description: "Build a human-in-the-loop LangGraph agent in Angular — pause runs before money moves with a structured approval dialog from @threadplane/chat and @threadplane/langgraph."
+description: "Build a human-in-the-loop LangGraph agent in Angular — pause runs before money moves with a structured approval dialog from the Threadplane libraries."
 date: 2026-05-28
 tags: [tutorial, langgraph, angular, agents, hitl, interrupts]
 author: brian

apps/website/content/blog/2026-06-04-human-in-the-loop-ag-ui-agents-in-angular.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Human-in-the-Loop AG-UI Agents in Angular"
-description: "Build a human-in-the-loop AG-UI agent in Angular — the same chat-approval-card composition from the LangGraph version, wired to an AG-UI-fronted LangGraph backend via @threadplane/ag-ui."
+description: "Build a human-in-the-loop AG-UI agent in Angular — the same chat-approval-card composition as the LangGraph version, wired to AG-UI via @threadplane/ag-ui."
 date: 2026-06-04
 tags: [tutorial, ag-ui, angular, agents, hitl, interrupts]
 author: brian

apps/website/content/blog/2026-06-24-threadplane-earns-grade-a-hvtrust.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Threadplane Earns a Grade A for Trust"
-description: "An independent tracker scored Threadplane's supply-chain trust at 82.8/100 — a Grade A, #7 of 75 agent frameworks, and the only Angular agent framework on the board. Here's the work behind the grade, and why it matters for agent frameworks specifically."
+description: "An independent tracker scored Threadplane's supply-chain trust at 82.8/100 — Grade A, #7 of 75 agent frameworks. The work behind the grade, and why it matters."
 date: 2026-06-24
 tags: [announcement, security, supply-chain, open-source, trust]
 author: brian

apps/website/content/blog/2026-08-13-angular-chat-app-tutorial-with-ag-ui.mdx

@@ -1,6 +1,6 @@
 ---
 title: 'Angular Chat App Tutorial with AG-UI'
-description: 'Build an Angular chat app on AG-UI where the browser owns its own tools — action, view, and ask client tools rendering real components inline, plus agent-shared state.'
+description: 'Build an Angular chat app on AG-UI where the browser owns its own tools — action, view, and ask tools rendering real components inline, plus shared state.'
 date: 2026-08-13
 tags: [tutorial, ag-ui, angular, client-tools, agentic-ui]
 author: brian

apps/website/src/app/blog/[slug]/page.tsx

@@ -8,7 +8,7 @@ import { Eyebrow } from '../../../components/ui/Eyebrow';
 import { getAllPosts, getPostBySlug, formatPostDate, readingTimeMin } from '../../../lib/blog';
 import { getAuthor } from '../../../lib/blog-authors';
 import { extractHeadings } from '../../../lib/extract-headings';
-import { createPageMetadata, ogImagePath } from '../../../lib/site-metadata';
+import { clampMetaDescription, createPageMetadata, ogImagePath } from '../../../lib/site-metadata';
 import { getPostLastModified, publishedDate } from '../../../lib/sitemap-dates';
 import { JsonLd } from '../../../components/shared/JsonLd';
 import { blogPostingJsonLd, breadcrumbJsonLd } from '../../../lib/structured-data';
@@ -36,7 +36,7 @@ export async function generateMetadata({ params }: Params): Promise<Metadata> {
 
   return createPageMetadata({
     title: `${post.frontmatter.title} — Threadplane`,
-    description: post.frontmatter.description,
+    description: clampMetaDescription(post.frontmatter.description),
     pathname,
     type: 'article',
     image: ogImagePath(post.slug),
@@ -72,7 +72,8 @@ export default async function BlogPostPage({ params }: Params) {
   const postData = published
     ? blogPostingJsonLd({
         title: post.frontmatter.title,
-        description: post.frontmatter.description,
+        // Same clamp as the meta description so the two never diverge.
+        description: clampMetaDescription(post.frontmatter.description),
         slug: post.slug,
         datePublished: published.toISOString(),
         dateModified: lastModified?.toISOString(),

apps/website/src/app/pricing/page.tsx

@@ -12,7 +12,7 @@ import { createPageMetadata } from '../../lib/site-metadata';
 export const metadata = createPageMetadata({
   title: 'Pricing — Threadplane',
   description:
-    'Most Threadplane packages are MIT-licensed. @threadplane/chat is free for permitted noncommercial use and evaluation; commercial production plans start at $29 per developer per month. Threadplane runs in your own stack.',
+    'Most Threadplane packages are MIT-licensed. @threadplane/chat plans start at $29 per developer per month. Threadplane runs in your own stack.',
   pathname: '/pricing',
   type: 'website',
 });

apps/website/src/lib/docs.spec.ts

@@ -118,6 +118,20 @@ describe('website docs bindings', () => {
     );
   });
 
+  it('keeps every description within the search-snippet budget', () => {
+    // GSC follow-up to #826: 160+ char descriptions get re-truncated by
+    // Google mid-sentence. The clamp must also never leave the legacy
+    // mid-word '...' cut.
+    const slugs = getAllDocSlugs();
+    expect(slugs.length).toBeGreaterThan(100); // sweep must not pass on an empty list
+    for (const { library, section, slug } of slugs) {
+      const description = getDocMetadata(library, section, slug)?.description;
+      expect(description, `${library}/${section}/${slug}`).toBeTruthy();
+      expect(description!.length, `${library}/${section}/${slug}`).toBeLessThanOrEqual(160);
+      expect(description!.endsWith('...'), `${library}/${section}/${slug}`).toBe(false);
+    }
+  });
+
   it('derives mostly unique descriptions from page content', () => {
     const descriptions = getAllDocSlugs()
       .map(({ library, section, slug }) => getDocMetadata(library, section, slug)?.description)

apps/website/src/lib/docs.ts

@@ -2,7 +2,7 @@ import fs from 'fs';
 import path from 'path';
 import type { Metadata } from 'next';
 import { docsConfig, type DocsPage, getLibraryConfig, getLibraryPages } from './docs-config';
-import { createPageMetadata } from './site-metadata';
+import { clampMetaDescription, createPageMetadata } from './site-metadata';
 
 const resolveContentDir = (library: string): string => {
   const workspacePath = path.join(process.cwd(), 'apps', 'website', 'content', 'docs', library);
@@ -79,16 +79,18 @@ function extractFirstParagraph(content: string): string | null {
       continue;
     }
 
-    return normalized.length > 180 ? `${normalized.slice(0, 177).trimEnd()}...` : normalized;
+    return clampMetaDescription(normalized);
   }
 
   return null;
 }
 
 function getDocDescription(content: string, fallback: string): string {
+  // Clamped here (not only in createPageMetadata) so the docs JSON-LD, which
+  // reads this value directly, stays byte-identical to the meta description.
   const frontmatterDescription = readFrontmatterDescription(content);
-  if (frontmatterDescription) return normalizeDescription(frontmatterDescription);
-  return extractFirstParagraph(content) ?? fallback;
+  if (frontmatterDescription) return clampMetaDescription(normalizeDescription(frontmatterDescription));
+  return extractFirstParagraph(content) ?? clampMetaDescription(fallback);
 }
 
 export function getDocBySlug(library: string, section: string, slug: string): ResolvedDoc | null {

apps/website/src/lib/site-metadata.spec.ts

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { describe, expect, it } from 'vitest';
 import {
+  clampMetaDescription,
   DEFAULT_META_DESCRIPTION,
   HERO_SUBHEAD,
   LONG_SUBHEAD,
@@ -54,6 +55,49 @@ describe('site positioning copy', () => {
   });
 });
 
+describe('clampMetaDescription', () => {
+  it('passes short descriptions through untouched', () => {
+    expect(clampMetaDescription('Short and sweet.')).toBe('Short and sweet.');
+  });
+
+  it('collapses internal whitespace', () => {
+    expect(clampMetaDescription('  a \n  b  ')).toBe('a b');
+  });
+
+  it('prefers a sentence boundary once past 60% of the budget', () => {
+    const first = 'This first sentence lands comfortably past the sixty percent mark of the one-sixty budget so the clamp should end exactly on it.';
+    const result = clampMetaDescription(`${first} This trailing sentence pushes the whole thing well over the limit.`);
+    expect(result).toBe(first);
+  });
+
+  it('falls back to a word boundary with an ellipsis', () => {
+    const words = Array.from({ length: 40 }, (_, i) => `word${i}`).join(' ');
+    const result = clampMetaDescription(words);
+    expect(result.length).toBeLessThanOrEqual(160);
+    expect(result.endsWith('\u2026')).toBe(true);
+    // never a mid-word cut: everything before the ellipsis is a whole word
+    expect(words.startsWith(result.slice(0, -1))).toBe(true);
+    expect(words[result.length - 1]).toBe(' ');
+  });
+
+  it('never exceeds the budget', () => {
+    const long = 'x'.repeat(400);
+    expect(clampMetaDescription(long).length).toBeLessThanOrEqual(160);
+  });
+});
+
+describe('createPageMetadata description clamp', () => {
+  it('clamps the meta and OpenGraph descriptions centrally', () => {
+    const metadata = createPageMetadata({
+      title: 'T',
+      description: `${'Lead sentence that is deliberately made long enough to pass the sixty percent sentence-boundary threshold of the budget for this clamp.'} Overflow text beyond the snippet budget.`,
+      pathname: '/x',
+    });
+    expect(String(metadata.description).length).toBeLessThanOrEqual(160);
+    expect(metadata.openGraph?.description).toBe(metadata.description);
+  });
+});
+
 describe('createPageMetadata article fields', () => {
   it('emits openGraph article dates, authors, and tags', () => {
     const metadata = createPageMetadata({
@@ -159,3 +203,23 @@ describe('brand name', () => {
     expect(SITE_NAME).toBe('Threadplane');
   });
 });
+
+describe('blog frontmatter description budget', () => {
+  it('every post description fits a search snippet without clamping', () => {
+    // The runtime clamp guards the meta tag, but a hand-written description
+    // that needs clamping loses its author's chosen ending — keep the source
+    // honest. (Reads the real content files; blog.spec.ts mocks fs.)
+    const blogDir = path.join(resolveWebsiteDir(), 'content', 'blog');
+    const offenders: string[] = [];
+    for (const file of fs.readdirSync(blogDir).filter((f) => f.endsWith('.mdx'))) {
+      const source = fs.readFileSync(path.join(blogDir, file), 'utf8');
+      const description = source
+        .match(/^---\n[\s\S]*?^description:\s*['"]?(?<d>[^'"\n]+?)['"]?\s*$/m)
+        ?.groups?.['d'];
+      if (description && description.length > 160) {
+        offenders.push(`${file} (${description.length} chars)`);
+      }
+    }
+    expect(offenders).toEqual([]);
+  });
+});