refactor(website): finish the json-render rename; generalise style contracts

Two follow-ups from #923.

json-render on marketing surfaces
---------------------------------
#923 renamed the docs picker label but deliberately left the marketing
surfaces. They now agree: the homepage FeatureBlock eyebrow, the footer
link, and the three solutions architecture layers all read json-render.

Two hazards this surfaced:

- The footer derives cta_id from the visible label, so renaming the link
  would have silently split PostHog's footer_render into a new
  footer_json_render series. trackFooterCta now takes an optional
  explicit CtaId and the render link pins the original.
- The solutions page maps library name to href through a
  Record<string, string>. Renaming the data without the key returns
  undefined and renders the card unlinked — no error, no type failure.
  solutions-links.spec.ts asserts every layer resolves; mutation-tested
  by renaming one side only.

Style contracts
---------------
docs-sidebar-styles.spec.ts guarded two CSS declarations whose loss is
invisible to jsdom, but it was a one-off with an inline parser. It is
replaced by style-contract.ts plus a registry in style-contracts.spec.ts,
so adding a guard is one entry rather than a new file.

Seeded with four live rules, each mutation-tested by deleting the
declaration and by renaming the selector wholesale:

- .docs-sidebar-lib-item-text     flex column (the #892 collision)
- .docs-sidebar-lib-menu          max-height + overflow-y
- .docs-control-plane             position sticky + align-self
- [data-control-plane-pane]       overflow-y

Writing the registry found a bug in the extracted parser: a CSS comment
above a rule lands inside the selector capture, so the exact match never
fires and a guarded rule reports as missing. Comments are stripped first.

Also removes the DocsSidebar wrapper and its .docs-sidebar rule, dead
since #892 moved the docs nav into the control plane — only
DocsNavigation is imported, and the sole class usage was inside the dead
component. Its comment documented the same align-self hazard now held by
the .docs-control-plane contract.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: blove

apps/website/src/app/page.tsx

@@ -67,7 +67,7 @@ export default async function HomePage() {
       {/* Render */}
       <FeatureBlock
         id="render"
-        eyebrow="Render"
+        eyebrow="json-render"
         headline="Agent output, rendered as your components."
         body="The server emits a JSON spec. Angular renders it with components you own — json-render and A2UI both speak it."
         rows={[

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

@@ -22,9 +22,15 @@ interface PageProps {
   params: Promise<{ slug: string }>;
 }
 
-const LIBRARY_HREF: Record<string, string> = {
+/**
+ * Keyed by the display name in solutions-data. A miss renders the card
+ * unlinked rather than failing, and `Record<string, string>` will not catch a
+ * rename on either side — so `solutions-links.spec.ts` asserts every layer
+ * resolves.
+ */
+export const LIBRARY_HREF: Record<string, string> = {
   Agent: '/langgraph',
-  Render: '/render',
+  'json-render': '/render',
   Chat: '/chat',
 };
 

apps/website/src/components/docs/DocsSidebar.tsx

@@ -397,11 +397,3 @@ export function DocsNavigation({
     </div>
   );
 }
-
-export function DocsSidebar(props: DocsNavigationProps) {
-  return (
-    <aside className="docs-sidebar">
-      <DocsNavigation {...props} />
-    </aside>
-  );
-}

apps/website/src/components/landing/FeatureBlock.spec.tsx

@@ -3,7 +3,7 @@ import { describe, it, expect } from 'vitest';
 import { FeatureBlock } from './FeatureBlock';
 
 const base = {
-  eyebrow: 'Render',
+  eyebrow: 'json-render',
   headline: 'Agent output, rendered as your components.',
   body: 'Two sentences.',
   cta: { label: 'See it', href: '/render' },

apps/website/src/components/shared/Footer.tsx

@@ -1,7 +1,7 @@
 'use client';
 import { useState } from 'react';
 import Link from 'next/link';
-import { analyticsEvents } from '../../lib/analytics/events';
+import { analyticsEvents, type CtaId } from '../../lib/analytics/events';
 import { track, trackCtaClick, trackExternalLinkClick } from '../../lib/analytics/client';
 import { DEMOS, demoCtaSuffix } from '../../lib/demos';
 import { LogoMark } from '../ui/LogoMark';
@@ -90,11 +90,18 @@ function NewsletterForm() {
 }
 
 export function Footer() {
-  const trackFooterCta = (label: string, href: string) => {
+  /**
+   * `ctaId` defaults to a slug of the label. Pass it explicitly when the visible
+   * text changes but the analytics series should stay continuous — renaming
+   * "Render" to "json-render" would otherwise silently split footer_render into
+   * a new footer_json_render series.
+   */
+  const trackFooterCta = (label: string, href: string, ctaId?: CtaId) => {
     trackCtaClick({
       surface: 'footer',
       destination_url: href,
-      cta_id: `footer_${label.toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_|_$/g, '')}`,
+      cta_id:
+        ctaId ?? `footer_${label.toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_|_$/g, '')}`,
       cta_text: label,
     });
   };
@@ -200,8 +207,8 @@ export function Footer() {
               AG-UI
             </Link>
             <Link href="/render" className="transition-colors footer-link"
-              onClick={() => trackFooterCta('Render', '/render')}>
-              Render
+              onClick={() => trackFooterCta('json-render', '/render', 'footer_render')}>
+              json-render
             </Link>
             <Link href="/chat" className="transition-colors footer-link"
               onClick={() => trackFooterCta('Chat', '/chat')}>

apps/website/src/lib/solutions-data.ts

@@ -124,7 +124,7 @@ export const SOLUTIONS: SolutionConfig[] = [
         role: 'Production agent state with first-class interrupt support. Every agent action can require human approval before execution. Durable thread persistence preserves the full record of every tool call and state transition.',
       },
       {
-        library: 'Render',
+        library: 'json-render',
         pkg: '@threadplane/render',
         role: 'Approval workflows rendered as structured UI — not chat messages. The agent proposes an action, renders a confirmation card, and waits for the human gate before proceeding.',
       },
@@ -217,7 +217,7 @@ export const SOLUTIONS: SolutionConfig[] = [
         role: 'Streams query results token-by-token as the LangGraph agent reasons over your data. Thread persistence means users can refine questions without re-running expensive queries.',
       },
       {
-        library: 'Render',
+        library: 'json-render',
         pkg: '@threadplane/render',
         role: 'The agent emits chart specs, data tables, and KPI cards as structured render specs. Your Angular components render them with streaming JSON patches — live-updating visualizations as data arrives.',
       },
@@ -295,7 +295,7 @@ export class DashboardComponent {
         role: 'LangGraph interrupts let the agent pause before sensitive actions — refunds, account changes, escalations. Thread persistence preserves the full conversation across bot-to-human handoffs.',
       },
       {
-        library: 'Render',
+        library: 'json-render',
         pkg: '@threadplane/render',
         role: 'The agent renders structured UI — order summaries, refund confirmations, knowledge base cards — instead of dumping text. Customers see clean, actionable information.',
       },

apps/website/src/lib/solutions-links.spec.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from 'vitest';
+import { LIBRARY_HREF } from '../app/solutions/[slug]/page';
+import { SOLUTIONS } from './solutions-data';
+
+/**
+ * Every architecture layer names a library, and the solutions page turns that
+ * name into an href through a plain `Record<string, string>`. A miss is silent
+ * — the card just renders without a link — and the types cannot catch a rename
+ * on one side only.
+ */
+describe('solutions architecture layers', () => {
+  it('every named library resolves to a href', () => {
+    const unresolved = SOLUTIONS
+      .flatMap((s) => s.architectureLayers.map((l) => l.library))
+      .filter((library) => !LIBRARY_HREF[library]);
+
+    expect(unresolved).toEqual([]);
+  });
+
+  it('names the render library the way the docs do', () => {
+    const names = new Set(
+      SOLUTIONS.flatMap((s) => s.architectureLayers.map((l) => l.library)),
+    );
+
+    expect(names.has('json-render')).toBe(true);
+    expect(names.has('Render')).toBe(false);
+  });
+});

apps/website/src/styles/docs-sidebar-styles.spec.ts

@@ -729,17 +729,6 @@
   color: var(--color-text-primary);
 }
 
-.docs-sidebar {
-  border-right: 1px solid var(--color-border);
-  background: var(--color-surface);
-  position: sticky;
-  top: var(--nav-h);
-  /* Without align-self the flex row stretches the aside to the article's full
-   * height (measured 10,030px), so its overflow-y:auto never engaged. */
-  align-self: flex-start;
-  min-height: calc(100vh - var(--nav-h));
-  max-height: calc(100vh - var(--nav-h));
-}
 .docs-sidebar-lib-trigger {
   background: var(--color-surface);
   border: 1px solid var(--color-border);

apps/website/src/styles/docs.css

@@ -0,0 +1,37 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * Reading declarations out of a stylesheet, for rules whose loss is *silent*.
+ *
+ * jsdom does not apply stylesheets, so a component test renders the same DOM
+ * whether or not a load-bearing declaration exists. That gap is how PR #892
+ * shipped a docs picker whose title and description collided into one run-on
+ * line: the JSX moved off Tailwind onto semantic class names, the
+ * `flex flex-col` was never ported, and every test stayed green.
+ *
+ * Use this only for declarations where the failure mode is plausible-but-wrong
+ * rendering. Ordinary styling belongs in review, not in a test.
+ *
+ * Limitation: this is a flat scan, not a CSS parser. Rules nested in
+ * `@media` blocks are merged into the same selector's declarations, and
+ * cascade order is not modelled. That is fine for asserting "this declaration
+ * exists somewhere for this selector" and wrong for anything subtler.
+ */
+export function loadStylesheet(file: string): string {
+  return readFileSync(join(__dirname, file), 'utf8');
+}
+
+/** Merged declaration text for every rule whose selector list contains `selector`. */
+export function declarationsFor(css: string, selector: string): string {
+  // Comments must go first: a `/* ... */` above a rule lands inside the
+  // selector capture below, and the exact match then never fires. That reads
+  // as "the rule is missing" — which is how a contract would report a false
+  // failure the moment someone documented the rule it guards.
+  const withoutComments = css.replace(/\/\*[\s\S]*?\*\//g, '');
+
+  return [...withoutComments.matchAll(/([^{}]+)\{([^{}]*)\}/g)]
+    .filter((match) => match[1].split(',').some((part) => part.trim() === selector))
+    .map((match) => match[2])
+    .join(';');
+}