From 1b8a870f2b09831cbe53acdb1869de8009d29f4d Mon Sep 17 00:00:00 2001
From: anurag629 <akvermaav629@gmail.com>
Date: Wed, 8 Jul 2026 14:13:36 +0530
Subject: [PATCH] feat: structured data (JSON-LD) and metadata completeness

Add schema.org structured data and fill metadata gaps so search and AI
crawlers can understand the site and each tool.

- lib/jsonLd.ts (new): one home for all JSON-LD builders, each derived from
  the TOOLS registry so it can't drift from what renders.
  - FAQPage from the registry FAQs (the FAQs were already written but nothing
    emitted them); gated to pages that actually render an FAQ section
  - Organization + WebSite + ItemList @graph on the homepage, linked by @id
  - BreadcrumbList on tool pages (Home > Tool)
  - toolJsonLd (SoftwareApplication) moved here from lib/toolMetadata.ts
- ToolPageLayout: emit the three JSON-LD blocks and render a real visible
  Home > Tool breadcrumb (so the schema represents visible content). The
  heroBreadcrumb tagline sits outside the <nav> so it isn't announced as a
  crumb, and the current crumb uses --fg to clear WCAG AA contrast.
- Homepage: canonical, inheriting the root OpenGraph rather than clobbering it.
- Root metadata: OpenGraph locale/title/description and twitter:site.
- Per-tool OpenGraph gains siteName + locale.

Deliberately skipped: SearchAction/sitelinks searchbox (no site search;
deprecated in 2024), and any aggregateRating (no honest ratings to claim).

All JSON-LD verified as valid against the rendered HTML. build, lint, and
27 tests pass.
---
 app/layout.tsx                       |  5 ++
 app/page.tsx                         | 13 ++++
 components/shared/ToolPageLayout.tsx | 46 +++++++++----
 lib/jsonLd.ts                        | 97 ++++++++++++++++++++++++++++
 lib/toolMetadata.ts                  | 20 ++----
 5 files changed, 154 insertions(+), 27 deletions(-)
 create mode 100644 lib/jsonLd.ts

diff --git a/app/layout.tsx b/app/layout.tsx
index 16a6a06..185d7f5 100644
--- a/app/layout.tsx
+++ b/app/layout.tsx
@@ -51,9 +51,14 @@ export const metadata: Metadata = {
     type: "website",
     siteName: "CODERCOPS Tools",
     url: "https://tools.codercops.com",
+    locale: "en_US",
+    title: "CODERCOPS Tools — Developer Utilities",
+    description:
+      "Free, fast, privacy-first developer tools: JSON formatter, JWT decoder, Base64 encoder, and more. Runs entirely in your browser.",
   },
   twitter: {
     card: "summary_large_image",
+    site: "@codercops",
     creator: "@codercops",
   },
 };
diff --git a/app/page.tsx b/app/page.tsx
index 88c2e8e..d8ab0a4 100644
--- a/app/page.tsx
+++ b/app/page.tsx
@@ -1,11 +1,24 @@
+import type { Metadata } from "next";
 import { ToolCard } from "@/components/shared/ToolCard";
 import { CtaBanner } from "@/components/shared/CtaBanner";
 import { Footer } from "@/components/shared/Footer";
 import { TOOLS } from "@/lib/tools";
+import { homeJsonLd } from "@/lib/jsonLd";
+
+// Only the canonical is set here; title, description, and OpenGraph are inherited
+// from the root layout (Next merges metadata shallowly, so re-declaring openGraph
+// would drop the root's siteName/locale/type from the homepage).
+export const metadata: Metadata = {
+  alternates: { canonical: "/" },
+};
 
 export default function HomePage() {
   return (
     <>
+      <script
+        type="application/ld+json"
+        dangerouslySetInnerHTML={{ __html: JSON.stringify(homeJsonLd()) }}
+      />
       <section className="relative">
         <div className="absolute inset-0 grid-bg opacity-50" />
         <div className="relative mx-auto max-w-7xl px-4 sm:px-6 pt-20 pb-14">
diff --git a/components/shared/ToolPageLayout.tsx b/components/shared/ToolPageLayout.tsx
index d2fffe8..10a45ab 100644
--- a/components/shared/ToolPageLayout.tsx
+++ b/components/shared/ToolPageLayout.tsx
@@ -1,5 +1,6 @@
+import Link from "next/link";
 import { cn } from "@/lib/cn";
-import { toolJsonLd } from "@/lib/toolMetadata";
+import { toolJsonLd, breadcrumbJsonLd, faqJsonLd } from "@/lib/jsonLd";
 import type { Tool } from "@/lib/tools";
 import { CtaBanner } from "./CtaBanner";
 import { Faq } from "./Faq";
@@ -29,18 +30,41 @@ export function ToolPageLayout({
         type="application/ld+json"
         dangerouslySetInnerHTML={{ __html: JSON.stringify(toolJsonLd(tool)) }}
       />
+      <script
+        type="application/ld+json"
+        dangerouslySetInnerHTML={{ __html: JSON.stringify(breadcrumbJsonLd(tool)) }}
+      />
+      {tool.faqs.length > 0 && (
+        <script
+          type="application/ld+json"
+          dangerouslySetInnerHTML={{ __html: JSON.stringify(faqJsonLd(tool)) }}
+        />
+      )}
       <section className="mx-auto max-w-7xl w-full px-4 sm:px-6 pt-10 pb-6">
-        <div className="flex items-center gap-2 mb-4">
-          <span
-            className="font-mono text-[10.5px] tracking-[0.22em] uppercase"
-            style={{ color: `var(${tool.accentVar})` }}
-          >
-            /{tool.slug}
-          </span>
-          <span className="w-1 h-1 rounded-full bg-[var(--fg-dim)]" />
-          <span className="font-mono text-[10.5px] tracking-[0.22em] uppercase text-[var(--fg-dim)]">
-            {tool.heroBreadcrumb}
+        {/* The breadcrumb trail is only Home > Tool (matching the JSON-LD). The
+            heroBreadcrumb tagline sits outside the <nav>/<ol> so assistive tech
+            doesn't announce it as a third crumb. The current crumb uses --fg
+            (not the accent) so it clears WCAG AA contrast in both themes. */}
+        <div className="mb-4 flex flex-wrap items-center gap-2 font-mono text-[10.5px] tracking-[0.22em] uppercase">
+          <nav aria-label="Breadcrumb">
+            <ol className="flex items-center gap-2">
+              <li>
+                <Link href="/" className="text-[var(--fg-dim)] hover:text-[var(--fg)] transition-colors">
+                  Home
+                </Link>
+              </li>
+              <li aria-hidden="true" className="text-[var(--fg-dim)]">
+                /
+              </li>
+              <li aria-current="page" className="text-[var(--fg)]">
+                {tool.jsonLdName}
+              </li>
+            </ol>
+          </nav>
+          <span aria-hidden="true" className="text-[var(--fg-dim)]">
+            ·
           </span>
+          <span className="text-[var(--fg-dim)]">{tool.heroBreadcrumb}</span>
         </div>
         <h1 className="font-display text-4xl sm:text-5xl font-semibold tracking-tight text-[var(--fg)] leading-tight">
           {before}
diff --git a/lib/jsonLd.ts b/lib/jsonLd.ts
new file mode 100644
index 0000000..a36cd6d
--- /dev/null
+++ b/lib/jsonLd.ts
@@ -0,0 +1,97 @@
+// All schema.org JSON-LD builders in one place. Everything derives from the
+// TOOLS registry or SITE_URL, so the structured data can never drift from what
+// the pages actually render. Emitted as inline <script type="application/ld+json">,
+// which is inert data (not executable JS), so the nonce CSP does not apply.
+
+import { SITE_URL, TOOLS, type Tool } from "./tools";
+
+const ORG_ID = `${SITE_URL}/#organization`;
+const WEBSITE_ID = `${SITE_URL}/#website`;
+
+// The publisher is CODERCOPS (the agency). Keyed by an @id on this domain so the
+// WebSite node can reference it. sameAs lists only identities we can honestly
+// claim — the agency site is `url`; the GitHub org is the verified profile.
+const ORG_NODE = {
+  "@type": "Organization",
+  "@id": ORG_ID,
+  name: "CODERCOPS",
+  url: "https://www.codercops.com",
+  sameAs: ["https://github.com/codercops"],
+};
+
+// SoftwareApplication for a tool. No aggregateRating/review — there are no
+// accounts and no ratings we could honestly claim, and fabricating them is
+// against Google's policy.
+export function toolJsonLd(tool: Tool) {
+  return {
+    "@context": "https://schema.org",
+    "@type": "SoftwareApplication",
+    name: tool.jsonLdName,
+    applicationCategory: tool.applicationCategory,
+    operatingSystem: "Any (Browser)",
+    description: tool.jsonLdDescription,
+    url: `${SITE_URL}${tool.path}`,
+    offers: { "@type": "Offer", price: "0", priceCurrency: "USD" },
+    publisher: { "@type": "Organization", name: "CODERCOPS", url: "https://www.codercops.com" },
+  };
+}
+
+// A truthful two-level Home > Tool trail. The current page (position 2) omits
+// `item` per Google's spec. `name` uses jsonLdName so it matches both the
+// SoftwareApplication node and the visible breadcrumb rendered on the page.
+export function breadcrumbJsonLd(tool: Tool) {
+  return {
+    "@context": "https://schema.org",
+    "@type": "BreadcrumbList",
+    itemListElement: [
+      // No trailing slash, to match the homepage canonical Next emits (SITE_URL).
+      { "@type": "ListItem", position: 1, name: "Home", item: SITE_URL },
+      { "@type": "ListItem", position: 2, name: tool.jsonLdName },
+    ],
+  };
+}
+
+// FAQPage. Only call this for tools that actually render an FAQ section
+// (tool.faqs.length > 0), so the markup is always a true representation of the
+// visible page. json-formatter has no FAQs and must not emit this.
+export function faqJsonLd(tool: Tool) {
+  return {
+    "@context": "https://schema.org",
+    "@type": "FAQPage",
+    mainEntity: tool.faqs.map((f) => ({
+      "@type": "Question",
+      name: f.q,
+      acceptedAnswer: { "@type": "Answer", text: f.a },
+    })),
+  };
+}
+
+// Homepage @graph: Organization + WebSite + an ItemList of the tool collection.
+// The ItemList is generated from TOOLS in the same order the ToolCard grid
+// renders, so the structured list and the visible cards are always identical.
+export function homeJsonLd() {
+  return {
+    "@context": "https://schema.org",
+    "@graph": [
+      ORG_NODE,
+      {
+        "@type": "WebSite",
+        "@id": WEBSITE_ID,
+        url: SITE_URL,
+        name: "CODERCOPS Tools",
+        description: "Free, fast, privacy-first developer tools that run entirely in your browser.",
+        publisher: { "@id": ORG_ID },
+      },
+      {
+        "@type": "ItemList",
+        name: "CODERCOPS developer tools",
+        itemListElement: TOOLS.map((t, i) => ({
+          "@type": "ListItem",
+          position: i + 1,
+          name: t.jsonLdName,
+          url: `${SITE_URL}${t.path}`,
+        })),
+      },
+    ],
+  };
+}
diff --git a/lib/toolMetadata.ts b/lib/toolMetadata.ts
index 06fe289..aa99f9b 100644
--- a/lib/toolMetadata.ts
+++ b/lib/toolMetadata.ts
@@ -2,7 +2,8 @@ import type { Metadata } from "next";
 import { SITE_URL, type Tool } from "./tools";
 
 // Builds the per-tool Next Metadata from a manifest entry, so every tool page's
-// metadata block is identical in shape and can never drift.
+// metadata block is identical in shape and can never drift. The JSON-LD builders
+// live in lib/jsonLd.ts.
 export function generateToolMetadata(tool: Tool): Metadata {
   const url = `${SITE_URL}${tool.path}`;
   return {
@@ -14,21 +15,8 @@ export function generateToolMetadata(tool: Tool): Metadata {
       description: tool.ogDescription,
       url,
       type: "website",
+      siteName: "CODERCOPS Tools",
+      locale: "en_US",
     },
   };
 }
-
-// SoftwareApplication structured data for a tool.
-export function toolJsonLd(tool: Tool) {
-  return {
-    "@context": "https://schema.org",
-    "@type": "SoftwareApplication",
-    name: tool.jsonLdName,
-    applicationCategory: tool.applicationCategory,
-    operatingSystem: "Any (Browser)",
-    description: tool.jsonLdDescription,
-    url: `${SITE_URL}${tool.path}`,
-    offers: { "@type": "Offer", price: "0", priceCurrency: "USD" },
-    publisher: { "@type": "Organization", name: "CODERCOPS", url: "https://www.codercops.com" },
-  };
-}