pagegraph 0.10.1 → 0.12.0

package/README.md

@@ -1,21 +1,22 @@
 # pagegraph
 
-Route-declared SEO for TanStack Router. Each route declares its SEO policy once, in
-`staticData.seo` — the sitemap, `robots.txt`, breadcrumbs, JSON-LD, cross-links, and
-the CI check all derive from that one declaration. There is no second place to update,
-so nothing drifts. A public page that ships without a declaration **fails the build**.
+Route-declared SEO for TanStack Start and TanStack Router. Each route declares its SEO
+policy and head once, in `staticData.seo` — the `<head>`, sitemap, `robots.txt`,
+breadcrumbs, JSON-LD, cross-links, and the CI check all derive from that one
+declaration. There is no second place to update, so nothing drifts. A public page that
+ships without a declaration **fails the build**.
 
 ```mermaid
 flowchart LR
   subgraph declare["declare once"]
-    route["staticData.seo<br/>+ head()"]
+    route["staticData.seo (+ head)<br/>head: seo.head"]
   end
-  route --> seograph["SeoGraph<br/>(nodes + edges)"]
+  route --> seograph["SeoGraph<br/>(built by the Vite plugin)"]
   seograph --> sitemap["sitemap.xml"]
   seograph --> robots["robots.txt"]
   seograph --> check["pagegraph check · CI gate"]
   route --> head["&lt;head&gt; meta · canonical<br/>Breadcrumbs · JSON-LD"]
-  gate["seoRouteConfig (vite)"] -. "fails undeclared pages" .-> route
+  gate["pagegraph() (vite)"] -. "fails undeclared pages" .-> route
 ```
 
 ## Install
@@ -25,23 +26,43 @@ bun add pagegraph
 bun add -D lighthouse   # only for `pagegraph audit` performance evidence
 ```
 
-| Entry                        | Exports                                                                                        | Peers                                       |
-| ---------------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------- |
-| `pagegraph`        | `buildSeoGraph`, `renderSitemap`, `renderRobots`, `contentSignal`, `checkGraph`, `checkRenderedCoverage`, `decodeRenderedEdgeArtifact`, `inspectHtml` | —                                           |
-| `pagegraph/react`  | `createSeo` → `seoHead`, `Breadcrumbs`, JSON-LD generators                                     | `react`, `@tanstack/react-router`           |
-| `pagegraph/vite`   | `seoRouteConfig` coverage gate                                                                 | `vite`                                      |
-| `pagegraph/config` | `defineSeoConfig`, `viteGraphLoader`                                                           | `vite`                                      |
-| `pagegraph/audit`  | Audit services, scanner protocol, rules, and report schemas                                    | `effect`                                    |
-| `pagegraph` bin                   | CLI over the same graph                                                                        | bundled — runs on Bun                        |
+## What runs where
 
-The core and React import graphs have **zero runtime dependencies** — everything they use is a
-peer, and only the entries you import need those peers loaded.
+Every entry belongs to one place. Runtime entries are safe in a Worker, an SSR server, or a
+browser; build entries load your app through Vite, parse routes natively, or drive Node I/O.
+
+| Entry              | Runs in                       | Exports                                                                                                   | Peers                             |
+| ------------------ | ----------------------------- | --------------------------------------------------------------------------------------------------------- | --------------------------------- |
+| `pagegraph`        | runtime (Worker, SSR, browser) | `buildSeoGraph`, `contentCollection`, `renderSitemap`, `renderRobots`, `pageHeads`, `graphToJson`/`graphFromJson`, checks, `inspectHtml` | —                                 |
+| `pagegraph/react`  | runtime                       | `createSeo` → `seo.head`, `seoHead`, `Breadcrumbs`, JSON-LD generators                                    | `react`, `@tanstack/react-router` |
+| `pagegraph/tanstack-start/server` | runtime (Start server routes) | `robotsTxt`, `sitemapXml`, `seoGraph`, `seoSite`                                           | the `pagegraph()` plugin          |
+| `pagegraph/tanstack-start` | build (`vite.config.ts`, `seo.config.ts`) | `pagegraph()` Vite plugin, `tanstackStartGraph`, `evaluateAppGraph`                        | `vite`, `@tanstack/router-generator` |
+| `pagegraph/vite`   | build (`vite.config.ts`)      | `seoRouteConfig` coverage gate                                                                            | `vite`, `@tanstack/router-generator` |
+| `pagegraph/config` | build (`seo.config.ts`, CLI)  | `defineSeoConfig`, `viteGraphLoader`, `loadPageHeads`                                                     | `vite`                            |
+| `pagegraph/audit`  | build / CLI (Node or Bun)     | Audit services, scanner protocol, rules, and report schemas                                               | `effect`                          |
+| `pagegraph` bin    | CLI (Bun)                     | CLI over the same graph                                                                                   | bundled                           |
+
+Build entries resolve to a stub under the `workerd`, `worker`, and `browser` export conditions.
+A Worker or browser bundle that reaches one fails at import with an error naming the entry,
+instead of crashing on a native binding when a request first runs the code. The runtime entries
+have **zero runtime dependencies** beyond their listed peers; a test pins each entry's import
+graph.
 
 The CLI **bundles PageGraph's Effect and TypeSafe provider runtime**, so it does not depend on the
-app's Effect RC; it runs on [Bun](https://bun.sh) (`bunx pagegraph`). Agentic workflows load the
-OpenCode SDK and its private Effect runtime only when invoked. `vite` stays a peer — graph commands
+app's Effect version; it runs on [Bun](https://bun.sh) (`bunx pagegraph`). Agentic workflows load the
+OpenCode SDK only when invoked. The first workflow installs pinned OpenCode 2.0.22 into
+`~/.cache/pagegraph/opencode-2.0.22-2`, outside the app's dependency tree; subsequent workflows
+reuse the verified cache. This keeps consumer dependency overrides away from OpenCode's declared
+Effect and Drizzle versions. Executor plugins must use OpenCode's Effect version (`4.0.0-rc.112`).
+Bun and network access to npm are required for the first install. The pinned OpenCode client's
+HTTP error handling retains the method, path, status, and response body for diagnostics;
+undeclared error bodies are capped at 16 KiB.
+Discovery-only research gets one continuation to complete provider evidence. Every workflow failure
+after run creation writes `failure.json` in the run directory, with the stage, session ID when available,
+transcript, and cause chain. `vite` stays a peer — graph commands
 load your app through Vite at runtime — and `lighthouse` is only needed by `pagegraph audit`.
-Importing `pagegraph/audit` programmatically still needs `effect`.
+Importing `pagegraph/audit` programmatically needs `effect@^4.0.0`. The Effect and TypeSafe
+peers remain optional for other library entry points and the bundled CLI.
 
 ### Agent skill
 
@@ -54,7 +75,7 @@ pagegraph skills get core
 
 The skill is maintained at [skill-data/core/SKILL.md](skill-data/core/SKILL.md) and compiled into the CLI, so the instructions match the installed Pagegraph version. `skills get core` prints Markdown to stdout; `--json` returns a structured payload.
 
-## Quick start
+## Quick start (TanStack Start)
 
 **1. Bind your site identity once.** Route files never see an origin or a brand name.
 
@@ -62,7 +83,7 @@ The skill is maintained at [skill-data/core/SKILL.md](skill-data/core/SKILL.md)
 // lib/seo.ts
 import { createSeo } from "pagegraph/react";
 
-export const { seoHead } = createSeo({
+const site = createSeo({
   origin: "https://example.com",
   site: {
     name: "Example",
@@ -76,19 +97,17 @@ export const { seoHead } = createSeo({
     description: "What the company does.",
     sameAs: ["https://github.com/example"],
     contactPoint: { contactType: "support", email: "hi@example.com" },
-    address: {
-      streetAddress: "123 Example Street",
-      addressLocality: "Example City",
-      addressRegion: "CA",
-      postalCode: "94105",
-      addressCountry: "US",
-    },
   },
   website: { searchPath: "/docs?q={search_term_string}" },
 });
+
+export const seo = site; // seo.head for static routes
+export const { seoHead } = site;
 ```
 
-**2. Declare on the route.** Policy in `staticData.seo`, per-page content in `head()`.
+**2. Declare each page once.** `staticData.seo` holds the crawl policy and the head
+together; `seo.head` renders it. The graph and the checks read the same
+`staticData.seo.head` — the page and the graph cannot disagree.
 
 ```tsx
 export const Route = createFileRoute("/pricing")({
@@ -100,124 +119,112 @@ export const Route = createFileRoute("/pricing")({
       related: ["/features", "/docs"],
       link: { title: "Pricing", description: "Simple volume pricing." },
       modifiedAt: "2026-09-29", // sitemap <lastmod> and the freshness report
+      head: {
+        title: "Pricing — Example",
+        description: "Simple volume pricing.",
+        faqs: pricingFaqs,
+      },
     },
   },
-  head: (ctx) =>
-    seoHead(ctx, {
-      title: "Pricing — Example",
-      description: "Simple volume pricing.",
-    }),
+  head: seo.head,
+  component: PricingPage,
 });
 ```
 
-`seoHead` returns the `meta` + canonical `links` TanStack renders into `<head>` —
+`seo.head` returns the `meta` + canonical `links` TanStack renders into `<head>` —
 title, description, og/twitter cards, robots, and the JSON-LD each page warrants
-(BreadcrumbList always; Article, FAQPage, Service, ItemList when the instance
-declares them).
+(BreadcrumbList always; Article, FAQPage, Service, ItemList when the head declares
+them). A route that renders from `loaderData` calls `seoHead(ctx, instance)` in its
+own `head()` and declares a `titleTemplate` (`"%s | Example Blog"`): `seoHead` applies it,
+and the graph applies it to the route's collection pages.
 
-### Extensible JSON-LD
-
-The built-in generators are conveniences, not a closed schema registry. Define any
-`schema-dts` entity, link it to the plugin's stable site identities, and compose one
-site graph:
+**3. Register the plugin.** It builds the graph once per build (and on change in dev)
+inside your app's Vite pipeline — path aliases, `define`s, and content plugins such as
+Fumadocs apply, with no stubs — and ships it to the server runtime as data.
 
 ```ts
-import {
-  createSeo,
-  defineJsonLd,
-  extendJsonLd,
-  jsonLdRef,
-} from "pagegraph/react";
-
-export const seo = createSeo({
-  // site, organization, and website as above
-  jsonLd: {
-    site: (ids) => [
-      defineJsonLd({
-        "@type": "SoftwareApplication",
-        "@id": "https://example.com/#product",
-        name: "Example",
-        applicationCategory: "DeveloperApplication",
-        operatingSystem: "Web",
-        provider: jsonLdRef(ids.organization),
-      }),
-    ],
-    transform: (entry) => {
-      if (entry.kind === "organization") {
-        return extendJsonLd(entry.document, {
-          slogan: "Ship with confidence.",
-        });
-      }
-      return entry.document;
-    },
+// vite.config.ts
+import { pagegraph } from "pagegraph/tanstack-start";
+
+pagegraph({
+  origin: "https://example.com",
+  indexable: process.env.DEPLOY_ENV === "production", // previews disallow everything
+  robots: { contentSignal: "search=yes, ai-input=yes, ai-train=yes" },
+  collections: "src/lib/seo/collections.ts",
+  routeConfig: {
+    outputPath: fileURLToPath(new URL("./src/lib/route-config.ts", import.meta.url)),
+    publicGroups: ["(marketing)", "(docs)"],
+    enforceCoverageIn: ["(marketing)", "(docs)"],
+    alwaysDisallow: ["/dashboard", "/api"],
   },
 });
-
-const siteGraph = seo.generateSiteGraphSchema();
 ```
 
-`generateSiteGraphSchema()` includes Organization, WebSite, and configured site
-entities in one `@graph`. Organization and WebSite use stable `#organization` and
-`#website` IDs; articles and services provided by the site reference the same
-Organization. Existing individual generators remain available and are not transformed.
-
-Add page-specific entities through `seoHead`:
-
 ```ts
-head: (ctx) =>
-  seo.seoHead(ctx, {
-    title: "Example for developers",
-    description: "A focused description of the product.",
-    jsonLd: [
-      defineJsonLd({
-        "@type": "SoftwareApplication",
-        name: "Example",
-        url: "https://example.com/product",
-      }),
-    ],
-  });
+// src/lib/seo/collections.ts — evaluated in the app's Vite pipeline
+import { contentCollection } from "pagegraph";
+import { blogSource } from "../blog-source"; // e.g. a Fumadocs loader()
+
+export const collections = () => [
+  contentCollection({
+    route: "/blog/$slug",
+    source: "blog",
+    pages: blogSource.getPages(),
+    entry: (page) => ({
+      title: page.data.title,
+      description: page.data.description,
+      publishedAt: page.data.date,
+      related: page.data.related,
+    }),
+  }),
+];
 ```
 
-The transform sees discriminated generated and custom entries plus `origin`,
-`canonical`, and `entityIds`. Return the document to keep it, no value (or `false`)
-to suppress it, or an array to expand it. Output preserves caller order and never
-silently deduplicates entities.
+The plugin evaluates every route file that declares `staticData` — never the generated
+route tree — in a Node environment named `pagegraph`. A route that imports a module
+only the server runtime provides (`cloudflare:workers`) fails with its file name; add an
+app-only route to `exclude` (route-file globs).
 
-**3. Serve the projections.** Build the graph from your route tree, render strings.
+**4. Serve robots.txt and sitemap.xml.** One line each; the output depends on the
+deployment's origin and indexability, so they stay routes.
 
 ```ts
-// lib/seo/graph.ts — also the module the CLI loads
-import { buildSeoGraph } from "pagegraph";
+// src/routes/robots[.]txt.ts — sitemap[.]xml.ts is symmetric with sitemapXml
+import { robotsTxt } from "pagegraph/tanstack-start/server";
 
-export const loadSeoGraph = () =>
-  buildSeoGraph({ routeTree, collections: [blogCollection] });
+export const Route = createFileRoute("/robots.txt")({ server: { handlers: { GET: robotsTxt } } });
 ```
 
+**5. Gate CI.** The CLI reads the same graph through `seo.config.ts`:
+
 ```ts
-// routes/sitemap[.]xml.ts — robots[.]txt.ts is symmetric
-import { renderRobots, renderSitemap } from "pagegraph";
+// seo.config.ts
+import { defineSeoConfig } from "pagegraph/config";
+import { tanstackStartGraph } from "pagegraph/tanstack-start";
 
-renderSitemap(loadSeoGraph(), { origin, indexable: true });
-renderRobots(loadSeoGraph(), {
-  origin,
-  indexable: true,
-  disallow: routeConfig.robotsExclusions,
-  contentSignal: "search=yes, ai-input=yes, ai-train=yes",
+export default defineSeoConfig({
+  origin: "https://example.com",
+  loadGraph: tanstackStartGraph({ root: import.meta.dirname }),
 });
 ```
 
+```bash
+pagegraph check
+```
+
+### Without TanStack Start
+
+`buildSeoGraph({ routeTree, collections })` builds the same graph from any TanStack
+Router tree; render it with `renderSitemap(graph, { origin, indexable })` and
+`renderRobots(graph, { origin, indexable, disallow, contentSignal })`, and point
+`seo.config.ts` at it with `viteGraphLoader` (see [CLI](#cli)).
+
 `renderRobots` does not invent a Content-Signal. Pass `contentSignal` for
 the value (the plugin prefixes `Content-Signal: `), `directives` for extra
 group lines, and `transform` if you need to wrap or replace the whole file.
 Preview hosts (`indexable: false`) drop `contentSignal` and `directives`;
 `transform` still runs.
 
-**4. Gate CI.** The same graph, the same rules, exit 1 on structural violations.
-
-```bash
-pagegraph check
-```
-
 ## Agentic workflows
 
 PageGraph can combine the deterministic route graph with a project-owned embedded OpenCode agent,
@@ -285,6 +292,11 @@ After research is validated, the run directory contains `research.json`: an inco
 with the collected evidence, decision inputs, and OpenCode transcript. A downstream failure reports
 its path so the evidence remains available for diagnosis. Only a completed workflow writes
 `run.json` and `summary.md`; a research checkpoint is not a final recommendation.
+Model JSON drops null properties and array elements before validation. Schema validation collects all
+issues for one read-only repair turn. Every error after run creation writes `failure.json` in that
+run directory with the workflow, stage, available OpenCode session ID, transcript, and full cause
+chain. The error reports the artifact path and a next step; a failed artifact write preserves the
+original error with a note.
 
 | Command | Result |
 | --- | --- |
@@ -373,9 +385,10 @@ route's date is never inherited by its instances. Undated pages emit no
 
 ## Coverage gate (Vite)
 
-`seoRouteConfig` parses the route tree with `@tanstack/router-generator` (the same
-parser as the router) and fails `vite build` when a page in an enforced group has
-neither `staticData` nor `head`:
+`pagegraph({ routeConfig })` — or `seoRouteConfig` from `pagegraph/vite` in a Router-only
+app — parses the route tree with `@tanstack/router-generator` (the same parser as the
+router) and fails `vite build` when a page in an enforced group has neither `staticData`
+nor `head`:
 
 ```ts
 // vite.config.ts
@@ -390,14 +403,15 @@ seoRouteConfig({
 ```
 
 It also derives a small config module from the route tree: `robotsExclusions`
-(feed to `renderRobots`) and `reservedSegments` (top-level segments an app must
-not hand out as tenant/org slugs).
+(the plugin adds them to robots.txt; a Router-only app feeds them to `renderRobots`) and
+`reservedSegments` (top-level segments an app must not hand out as tenant/org slugs).
 
 ## CLI
 
-The graph commands acquire your graph through `seo.config.ts` at the app root —
-the `viteGraphLoader` evaluates your graph module inside a headless Vite server,
-so path aliases, content plugins, and virtual modules all resolve:
+The graph commands acquire your graph through `seo.config.ts` at the app root. A
+TanStack Start app uses `tanstackStartGraph` (above), which also supplies the robots
+policy. Otherwise `viteGraphLoader` evaluates your graph module inside a headless Vite
+server, so path aliases, content plugins, and virtual modules all resolve:
 
 ```ts
 // seo.config.ts
@@ -417,6 +431,28 @@ export default defineSeoConfig({
 });
 ```
 
+Build-time consumers of page titles and descriptions read the same graph:
+
+```ts
+import { loadPageHeads } from "pagegraph/config"; // build-only
+import { tanstackStartGraph } from "pagegraph/tanstack-start";
+
+const heads = await loadPageHeads(tanstackStartGraph({ root: import.meta.dirname }), {
+  exclude: ["/docs", "/docs/**"],
+});
+```
+
+`selectPageHeadNodes(graph, options)` selects the page nodes `pageHeads` reads.
+`pageHeads(graph, options)` returns `{ path, title, description }[]` from each node's
+`head` (a declared `staticData.seo.head`, or a collection instance through its route's title
+template), requiring nonblank titles and descriptions and naming the page on failure. `loadPageHeads`
+always disposes the acquired graph, including when validation fails. Page nodes
+carry a sitemap declaration or an instance; layouts are excluded. By default,
+selection excludes noindex pages, redirects and parameter templates, while retaining
+sitemap-disabled hubs. Set `indexable: false` to include those nonindexable nodes.
+`exclude` accepts exact paths and path globs (`*` within a segment, `**` across
+segments). Docs are ordinary pages; excluding them is caller policy, not a graph kind.
+
 ```bash
 pagegraph check                 # CI gate — exit 1 on structural violations
 pagegraph check --site <url>    # also check every declared page's rendered HTML
@@ -736,8 +772,11 @@ import {
   hasStructuralViolations,
   inspectHtml,
 } from "pagegraph";
+import { evaluateAppGraph } from "pagegraph/tanstack-start";
 
-expect(hasStructuralViolations(checkGraph(loadSeoGraph()))).toBe(false);
+// the graph the plugin ships, evaluated through your Vite config
+const { graph } = await evaluateAppGraph({ root: appRoot, mode: "production" });
+expect(hasStructuralViolations(checkGraph(graph))).toBe(false);
 
 // render a page however you like, then assert the head it actually ships
 const report = inspectHtml(url, 200, html);

package/dist/audit.d.ts

@@ -1,4 +1,4 @@
-import "./content-DVL2iyGU.js";
+import "./content-B1cPtL8b.js";
 import * as Context from "effect/Context";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";

package/dist/audit.js

@@ -1,4 +1,4 @@
-import { l as extractAnchors, r as extractPageContent, t as checkPageContent } from "./content-BE9KCTgb.js";
+import { l as extractAnchors, r as extractPageContent, t as checkPageContent } from "./content-kcEnQdfi.js";
 import { mkdir, mkdtemp, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import * as Context from "effect/Context";

package/dist/build-only/audit.d.ts

@@ -0,0 +1 @@
+export {}

package/dist/build-only/audit.js

@@ -0,0 +1,6 @@
+import { t as buildOnlyError } from "../message-DT_CjUdt.js";
+//#region src/build-only/audit.ts
+throw buildOnlyError("pagegraph/audit");
+//#endregion
+
+//# sourceMappingURL=audit.js.map

package/dist/build-only/audit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.js","names":[],"sources":["../../src/build-only/audit.ts"],"sourcesContent":["import { buildOnlyError } from \"./message\";\n\nthrow buildOnlyError(\"pagegraph/audit\");\n"],"mappings":";;AAEA,MAAM,eAAe,iBAAiB"}

package/dist/build-only/config.d.ts

@@ -0,0 +1 @@
+export {}

package/dist/build-only/config.js

@@ -0,0 +1,6 @@
+import { t as buildOnlyError } from "../message-DT_CjUdt.js";
+//#region src/build-only/config.ts
+throw buildOnlyError("pagegraph/config");
+//#endregion
+
+//# sourceMappingURL=config.js.map

package/dist/build-only/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","names":[],"sources":["../../src/build-only/config.ts"],"sourcesContent":["import { buildOnlyError } from \"./message\";\n\nthrow buildOnlyError(\"pagegraph/config\");\n"],"mappings":";;AAEA,MAAM,eAAe,kBAAkB"}

package/dist/build-only/tanstack-start.d.ts

@@ -0,0 +1 @@
+export {}

package/dist/build-only/tanstack-start.js

@@ -0,0 +1,6 @@
+import { t as buildOnlyError } from "../message-DT_CjUdt.js";
+//#region src/build-only/tanstack-start.ts
+throw buildOnlyError("pagegraph/tanstack-start");
+//#endregion
+
+//# sourceMappingURL=tanstack-start.js.map

package/dist/build-only/tanstack-start.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tanstack-start.js","names":[],"sources":["../../src/build-only/tanstack-start.ts"],"sourcesContent":["import { buildOnlyError } from \"./message\";\n\nthrow buildOnlyError(\"pagegraph/tanstack-start\");\n"],"mappings":";;AAEA,MAAM,eAAe,0BAA0B"}

package/dist/build-only/vite.d.ts

@@ -0,0 +1 @@
+export {}

package/dist/build-only/vite.js

@@ -0,0 +1,6 @@
+import { t as buildOnlyError } from "../message-DT_CjUdt.js";
+//#region src/build-only/vite.ts
+throw buildOnlyError("pagegraph/vite");
+//#endregion
+
+//# sourceMappingURL=vite.js.map

package/dist/build-only/vite.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vite.js","names":[],"sources":["../../src/build-only/vite.ts"],"sourcesContent":["import { buildOnlyError } from \"./message\";\n\nthrow buildOnlyError(\"pagegraph/vite\");\n"],"mappings":";;AAEA,MAAM,eAAe,gBAAgB"}