pagegraph 0.11.0 → 0.12.0

package/dist/graph-Bcsourlv.js

@@ -0,0 +1,162 @@
+import { t as applyTitleTemplate } from "./declare-D5o7hwmv.js";
+//#region src/core/graph.ts
+/** Kind for instances whose collection route carries no declaration to inherit. */
+const FALLBACK_KIND = "page";
+/**
+* Join a child's local path onto its parent's computed full path with the same
+* semantics as TanStack's route init (relative segments, index "/" inherits the
+* parent, pathless/group routes are transparent), then normalize trailing slashes.
+*/
+function joinPath(parent, seg) {
+	if (seg === void 0) return parent;
+	if (seg === "/") return parent;
+	const trimmed = seg.replace(/^\/+/, "").replace(/\/+$/, "");
+	return `${parent === "/" ? "" : parent}/${trimmed}`.replace(/\/{2,}/g, "/");
+}
+/** A route's declared head as graph data: templated title, description, and plain FAQs. */
+function declaredHead(seo) {
+	if (seo.head === void 0) return void 0;
+	return {
+		title: applyTitleTemplate(seo.titleTemplate, seo.head.title),
+		description: seo.head.description,
+		faqs: seo.head.faqs?.map(({ question, answer }) => ({
+			question,
+			answer
+		}))
+	};
+}
+/** Merge a route's declaration into an existing same-path node (deeper route wins). */
+function mergeSeo(base, override) {
+	return {
+		kind: override.kind,
+		crumb: override.crumb ?? base.crumb,
+		sitemap: override.sitemap ?? base.sitemap,
+		robots: override.robots ?? base.robots,
+		related: override.related ?? base.related,
+		link: override.link ?? base.link,
+		redirectTo: override.redirectTo ?? base.redirectTo,
+		modifiedAt: override.modifiedAt ?? base.modifiedAt,
+		head: override.head ?? base.head,
+		titleTemplate: override.titleTemplate ?? base.titleTemplate
+	};
+}
+/**
+* Walk the route tree building structural nodes and crumb-parent edges. `crumbStack`
+* holds the paths of crumb-declaring ancestors so each crumb node links to its nearest
+* crumb ancestor down the real route-parent chain (matching render-time breadcrumbs).
+*/
+function walkRoutes(route, parentPath, isRoot, nodes, edges, crumbStack) {
+	const path = isRoot ? "/" : joinPath(parentPath, route.options.path);
+	const seo = route.options.staticData?.seo;
+	if (seo) {
+		const existing = nodes.get(path);
+		if (existing) {
+			existing.policy = mergeSeo(existing.policy, seo);
+			existing.kind = existing.policy.kind;
+			existing.head = declaredHead(seo) ?? existing.head;
+		} else nodes.set(path, {
+			path,
+			kind: seo.kind,
+			source: "route",
+			policy: { ...seo },
+			head: declaredHead(seo)
+		});
+		const nearestCrumbAncestor = crumbStack[crumbStack.length - 1];
+		if (seo.crumb !== void 0 && nearestCrumbAncestor !== void 0) edges.push({
+			from: path,
+			to: nearestCrumbAncestor,
+			type: "crumb-parent"
+		});
+	}
+	const pushedCrumb = seo?.crumb !== void 0;
+	if (pushedCrumb) crumbStack.push(path);
+	for (const child of route.children ?? []) walkRoutes(child, path, false, nodes, edges, crumbStack);
+	if (pushedCrumb) crumbStack.pop();
+}
+/**
+* Add one collection's instance nodes, inheriting kind + sitemap policy from the
+* collection route's declaration, then append the edges it declares. A path already
+* owned by another node is a collision: the first owner keeps the path and the
+* conflict is reported (the `path-owner-collision` check turns it into a violation).
+*/
+function addCollection(nodes, edges, collisions, collection) {
+	const collectionNode = nodes.get(collection.route);
+	const kind = collectionNode?.kind ?? FALLBACK_KIND;
+	const sitemap = collectionNode?.policy.sitemap;
+	const titleTemplate = collectionNode?.policy.titleTemplate;
+	/**
+	* Paths this collection lost to an earlier owner. Their instances never enter
+	* the graph, so any edge declared out of them would dangle — and the dead-edge
+	* check only validates an edge's `to`, so nothing downstream would catch it.
+	*/
+	const rejected = /* @__PURE__ */ new Set();
+	for (const instance of collection.instances) {
+		const existing = nodes.get(instance.path);
+		if (existing) {
+			collisions.push({
+				path: instance.path,
+				sources: [existing.source, collection.source]
+			});
+			rejected.add(instance.path);
+			continue;
+		}
+		nodes.set(instance.path, {
+			path: instance.path,
+			kind,
+			source: collection.source,
+			policy: {
+				kind,
+				sitemap
+			},
+			head: {
+				title: applyTitleTemplate(titleTemplate, instance.title),
+				description: instance.description
+			},
+			instance: {
+				title: instance.title,
+				description: instance.description,
+				publishedAt: instance.publishedAt,
+				modifiedAt: instance.modifiedAt
+			}
+		});
+	}
+	for (const edge of collection.edges ?? []) {
+		if (rejected.has(edge.from)) continue;
+		edges.push(edge);
+	}
+}
+/**
+* Build the SEO graph from route declarations and content collections.
+*
+* Synchronous: the caller materializes its collections before calling, so there is
+* no async work here. Callers own the origin.
+*/
+function buildSeoGraph(input) {
+	const nodes = /* @__PURE__ */ new Map();
+	const edges = [];
+	const collisions = [];
+	walkRoutes(input.routeTree, "/", true, nodes, edges, []);
+	for (const collection of input.collections ?? []) addCollection(nodes, edges, collisions, collection);
+	for (const node of nodes.values()) {
+		if (node.source !== "route") continue;
+		for (const to of node.policy.related ?? []) edges.push({
+			from: node.path,
+			to,
+			type: "related"
+		});
+		if (node.policy.redirectTo !== void 0) edges.push({
+			from: node.path,
+			to: node.policy.redirectTo,
+			type: "redirect"
+		});
+	}
+	return {
+		nodes,
+		edges,
+		collisions
+	};
+}
+//#endregion
+export { buildSeoGraph as t };
+
+//# sourceMappingURL=graph-Bcsourlv.js.map

package/dist/graph-Bcsourlv.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-Bcsourlv.js","names":[],"sources":["../src/core/graph.ts"],"sourcesContent":["/**\n * SEO graph — the derived model that projections (sitemap, robots), the CLI, and\n * the check engine all read from. Built from route declarations (`staticData.seo`)\n * plus consumer-supplied content collections. This module is pure: no React, no\n * env, no knowledge of where instances come from. Origins and env-derived values\n * are injected by the callers of the projections, never read here.\n *\n * A node is one of:\n *  - a structural route (`source: \"route\"`), keyed by its normalized full path,\n *    merging a layout route's declaration (crumb) with its index child's (kind,\n *    sitemap policy) when both resolve to the same URL;\n *  - a content instance (`source` = the collection's label), keyed by the page URL\n *    and carrying page-level metadata.\n *\n * Edges: `crumb-parent` (breadcrumb ancestry), `related` (deliberate cross-links),\n * `collection-member` (membership in a curated set), and `redirect` (route aliases).\n * The route walk emits crumb/related/redirect edges from declarations; a collection\n * may declare any additional edges its instances need.\n */\n\nimport type { AnyRoute } from \"@tanstack/react-router\";\n\nimport { applyTitleTemplate, type PublicPath, type RouteSeo, type SeoKind } from \"./declare\";\n\n/**\n * Where a node came from: `\"route\"` for a structural route declaration, or the\n * `source` label of the collection that produced the instance (e.g. \"blog\").\n */\nexport type SeoSource = string;\n\nexport interface SeoNode {\n  /** Canonical path, no origin (e.g. \"/pricing\", \"/blog/my-post\"). */\n  path: string;\n  kind: SeoKind;\n  source: SeoSource;\n  /** Route-declared policy, or synthesized (kind + inherited sitemap) for instances. */\n  policy: RouteSeo;\n  /**\n   * The head the page ships: a static route's declared `head`, or an instance's\n   * title (through its route's `titleTemplate`) and description. Absent when the\n   * route computes its head at request time and no collection supplies it.\n   */\n  head?: SeoNodeHead | undefined;\n  instance?:\n    | {\n        title: string;\n        description?: string | undefined;\n        publishedAt?: string | undefined;\n        modifiedAt?: string | undefined;\n      }\n    | undefined;\n}\n\n/**\n * A node's head as graph data: the full title, description, and FAQ text. An\n * instance without a description still carries its title.\n */\nexport interface SeoNodeHead {\n  readonly title: string;\n  readonly description?: string | undefined;\n  readonly faqs?: ReadonlyArray<{ readonly question: string; readonly answer: string }> | undefined;\n}\n\nexport type SeoEdgeType = \"crumb-parent\" | \"related\" | \"redirect\" | \"collection-member\";\n\nexport interface SeoEdge {\n  from: string;\n  to: string;\n  type: SeoEdgeType;\n}\n\nexport interface SeoGraph {\n  nodes: Map<string, SeoNode>;\n  edges: Array<SeoEdge>;\n  /** Exact-path ownership conflicts encountered while assembling graph sources. */\n  collisions?: ReadonlyArray<{ path: string; sources: ReadonlyArray<SeoSource> }> | undefined;\n}\n\n/** One concrete page produced by a collection. */\nexport interface SeoInstance {\n  /** Canonical path of the page (e.g. \"/blog/my-post\"). */\n  readonly path: string;\n  readonly title: string;\n  readonly description?: string | undefined;\n  readonly publishedAt?: string | undefined;\n  readonly modifiedAt?: string | undefined;\n}\n\nexport interface SeoCollection {\n  /**\n   * The param route these instances render through (e.g. \"/blog/$slug\"). Instances\n   * inherit this route's declared policy (kind + sitemap) — the graph reads it from\n   * the structural node, so declarations stay the single source of truth.\n   */\n  readonly route: PublicPath;\n  /** The `source` stamped on every node this collection produces (e.g. \"blog\"). */\n  readonly source: SeoSource;\n  readonly instances: ReadonlyArray<SeoInstance>;\n  /** Edges the collection declares between its instances and the rest of the graph. */\n  readonly edges?: ReadonlyArray<SeoEdge> | undefined;\n}\n\n/**\n * The structural route shape the graph walks: a TanStack route tree has it\n * before `init()`, and an adapter can build it from parsed route files.\n */\nexport interface SeoRouteNode {\n  readonly options: {\n    readonly path?: string | undefined;\n    readonly staticData?: { readonly seo?: RouteSeo | undefined } | undefined;\n  };\n  readonly children?: ReadonlyArray<SeoRouteNode> | undefined;\n}\n\nexport interface BuildSeoGraphInput {\n  readonly routeTree: AnyRoute | SeoRouteNode;\n  readonly collections?: ReadonlyArray<SeoCollection> | undefined;\n}\n\n/** Kind for instances whose collection route carries no declaration to inherit. */\nconst FALLBACK_KIND: SeoKind = \"page\";\n\n\n/**\n * Join a child's local path onto its parent's computed full path with the same\n * semantics as TanStack's route init (relative segments, index \"/\" inherits the\n * parent, pathless/group routes are transparent), then normalize trailing slashes.\n */\nfunction joinPath(parent: string, seg: string | undefined): string {\n  if (seg === undefined) return parent; // pathless layout / route group\n  if (seg === \"/\") return parent; // index route resolves to its parent's URL\n  const trimmed = seg.replace(/^\\/+/, \"\").replace(/\\/+$/, \"\");\n  const joined = `${parent === \"/\" ? \"\" : parent}/${trimmed}`;\n  return joined.replace(/\\/{2,}/g, \"/\");\n}\n\n/** A route's declared head as graph data: templated title, description, and plain FAQs. */\nfunction declaredHead(seo: RouteSeo): SeoNodeHead | undefined {\n  if (seo.head === undefined) return undefined;\n  return {\n    title: applyTitleTemplate(seo.titleTemplate, seo.head.title),\n    description: seo.head.description,\n    faqs: seo.head.faqs?.map(({ question, answer }) => ({ question, answer })),\n  };\n}\n\n/** Merge a route's declaration into an existing same-path node (deeper route wins). */\nfunction mergeSeo(base: RouteSeo, override: RouteSeo): RouteSeo {\n  return {\n    kind: override.kind,\n    crumb: override.crumb ?? base.crumb,\n    sitemap: override.sitemap ?? base.sitemap,\n    robots: override.robots ?? base.robots,\n    related: override.related ?? base.related,\n    link: override.link ?? base.link,\n    redirectTo: override.redirectTo ?? base.redirectTo,\n    modifiedAt: override.modifiedAt ?? base.modifiedAt,\n    head: override.head ?? base.head,\n    titleTemplate: override.titleTemplate ?? base.titleTemplate,\n  };\n}\n\n/**\n * Walk the route tree building structural nodes and crumb-parent edges. `crumbStack`\n * holds the paths of crumb-declaring ancestors so each crumb node links to its nearest\n * crumb ancestor down the real route-parent chain (matching render-time breadcrumbs).\n */\nfunction walkRoutes(\n  route: SeoRouteNode,\n  parentPath: string,\n  isRoot: boolean,\n  nodes: Map<string, SeoNode>,\n  edges: Array<SeoEdge>,\n  crumbStack: Array<string>,\n): void {\n  const path = isRoot ? \"/\" : joinPath(parentPath, route.options.path);\n  const seo = route.options.staticData?.seo;\n\n  if (seo) {\n    const existing = nodes.get(path);\n    if (existing) {\n      existing.policy = mergeSeo(existing.policy, seo);\n      existing.kind = existing.policy.kind;\n      // A head renders with its own route's template, never one merged from a layout.\n      existing.head = declaredHead(seo) ?? existing.head;\n    } else {\n      nodes.set(path, { path, kind: seo.kind, source: \"route\", policy: { ...seo }, head: declaredHead(seo) });\n    }\n\n    const nearestCrumbAncestor = crumbStack[crumbStack.length - 1];\n    if (seo.crumb !== undefined && nearestCrumbAncestor !== undefined) {\n      edges.push({ from: path, to: nearestCrumbAncestor, type: \"crumb-parent\" });\n    }\n  }\n\n  const pushedCrumb = seo?.crumb !== undefined;\n  if (pushedCrumb) crumbStack.push(path);\n  for (const child of route.children ?? []) {\n    walkRoutes(child, path, false, nodes, edges, crumbStack);\n  }\n  if (pushedCrumb) crumbStack.pop();\n}\n\n/**\n * Add one collection's instance nodes, inheriting kind + sitemap policy from the\n * collection route's declaration, then append the edges it declares. A path already\n * owned by another node is a collision: the first owner keeps the path and the\n * conflict is reported (the `path-owner-collision` check turns it into a violation).\n */\nfunction addCollection(\n  nodes: Map<string, SeoNode>,\n  edges: Array<SeoEdge>,\n  collisions: Array<{ path: string; sources: ReadonlyArray<SeoSource> }>,\n  collection: SeoCollection,\n): void {\n  const collectionNode = nodes.get(collection.route);\n  const kind = collectionNode?.kind ?? FALLBACK_KIND;\n  const sitemap = collectionNode?.policy.sitemap;\n  const titleTemplate = collectionNode?.policy.titleTemplate;\n\n  /**\n   * Paths this collection lost to an earlier owner. Their instances never enter\n   * the graph, so any edge declared out of them would dangle — and the dead-edge\n   * check only validates an edge's `to`, so nothing downstream would catch it.\n   */\n  const rejected = new Set<string>();\n\n  for (const instance of collection.instances) {\n    const existing = nodes.get(instance.path);\n    if (existing) {\n      collisions.push({ path: instance.path, sources: [existing.source, collection.source] });\n      rejected.add(instance.path);\n      continue;\n    }\n    nodes.set(instance.path, {\n      path: instance.path,\n      kind,\n      source: collection.source,\n      policy: { kind, sitemap },\n      head: { title: applyTitleTemplate(titleTemplate, instance.title), description: instance.description },\n      instance: {\n        title: instance.title,\n        description: instance.description,\n        publishedAt: instance.publishedAt,\n        modifiedAt: instance.modifiedAt,\n      },\n    });\n  }\n\n  for (const edge of collection.edges ?? []) {\n    if (rejected.has(edge.from)) continue;\n    edges.push(edge);\n  }\n}\n\n/**\n * Build the SEO graph from route declarations and content collections.\n *\n * Synchronous: the caller materializes its collections before calling, so there is\n * no async work here. Callers own the origin.\n */\nexport function buildSeoGraph(input: BuildSeoGraphInput): SeoGraph {\n  const nodes = new Map<string, SeoNode>();\n  const edges: Array<SeoEdge> = [];\n  const collisions: Array<{ path: string; sources: ReadonlyArray<SeoSource> }> = [];\n\n  walkRoutes(input.routeTree as unknown as SeoRouteNode, \"/\", true, nodes, edges, []);\n\n  for (const collection of input.collections ?? []) {\n    addCollection(nodes, edges, collisions, collection);\n  }\n\n  for (const node of nodes.values()) {\n    if (node.source !== \"route\") continue;\n    for (const to of node.policy.related ?? []) {\n      edges.push({ from: node.path, to, type: \"related\" });\n    }\n    if (node.policy.redirectTo !== undefined) {\n      edges.push({ from: node.path, to: node.policy.redirectTo, type: \"redirect\" });\n    }\n  }\n\n  return { nodes, edges, collisions };\n}\n"],"mappings":"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"}

package/dist/graph-BxCY90vq.d.ts

@@ -0,0 +1,104 @@
+import { i as RouteSeo, n as PublicPath, o as SeoKind } from "./declare-DVgdEdOL.js";
+import { AnyRoute } from "@tanstack/react-router";
+//#region src/core/graph.d.ts
+/**
+ * Where a node came from: `"route"` for a structural route declaration, or the
+ * `source` label of the collection that produced the instance (e.g. "blog").
+ */
+type SeoSource = string;
+interface SeoNode {
+  /** Canonical path, no origin (e.g. "/pricing", "/blog/my-post"). */
+  path: string;
+  kind: SeoKind;
+  source: SeoSource;
+  /** Route-declared policy, or synthesized (kind + inherited sitemap) for instances. */
+  policy: RouteSeo;
+  /**
+   * The head the page ships: a static route's declared `head`, or an instance's
+   * title (through its route's `titleTemplate`) and description. Absent when the
+   * route computes its head at request time and no collection supplies it.
+   */
+  head?: SeoNodeHead | undefined;
+  instance?: {
+    title: string;
+    description?: string | undefined;
+    publishedAt?: string | undefined;
+    modifiedAt?: string | undefined;
+  } | undefined;
+}
+/**
+ * A node's head as graph data: the full title, description, and FAQ text. An
+ * instance without a description still carries its title.
+ */
+interface SeoNodeHead {
+  readonly title: string;
+  readonly description?: string | undefined;
+  readonly faqs?: ReadonlyArray<{
+    readonly question: string;
+    readonly answer: string;
+  }> | undefined;
+}
+type SeoEdgeType = "crumb-parent" | "related" | "redirect" | "collection-member";
+interface SeoEdge {
+  from: string;
+  to: string;
+  type: SeoEdgeType;
+}
+interface SeoGraph {
+  nodes: Map<string, SeoNode>;
+  edges: Array<SeoEdge>;
+  /** Exact-path ownership conflicts encountered while assembling graph sources. */
+  collisions?: ReadonlyArray<{
+    path: string;
+    sources: ReadonlyArray<SeoSource>;
+  }> | undefined;
+}
+/** One concrete page produced by a collection. */
+interface SeoInstance {
+  /** Canonical path of the page (e.g. "/blog/my-post"). */
+  readonly path: string;
+  readonly title: string;
+  readonly description?: string | undefined;
+  readonly publishedAt?: string | undefined;
+  readonly modifiedAt?: string | undefined;
+}
+interface SeoCollection {
+  /**
+   * The param route these instances render through (e.g. "/blog/$slug"). Instances
+   * inherit this route's declared policy (kind + sitemap) — the graph reads it from
+   * the structural node, so declarations stay the single source of truth.
+   */
+  readonly route: PublicPath;
+  /** The `source` stamped on every node this collection produces (e.g. "blog"). */
+  readonly source: SeoSource;
+  readonly instances: ReadonlyArray<SeoInstance>;
+  /** Edges the collection declares between its instances and the rest of the graph. */
+  readonly edges?: ReadonlyArray<SeoEdge> | undefined;
+}
+/**
+ * The structural route shape the graph walks: a TanStack route tree has it
+ * before `init()`, and an adapter can build it from parsed route files.
+ */
+interface SeoRouteNode {
+  readonly options: {
+    readonly path?: string | undefined;
+    readonly staticData?: {
+      readonly seo?: RouteSeo | undefined;
+    } | undefined;
+  };
+  readonly children?: ReadonlyArray<SeoRouteNode> | undefined;
+}
+interface BuildSeoGraphInput {
+  readonly routeTree: AnyRoute | SeoRouteNode;
+  readonly collections?: ReadonlyArray<SeoCollection> | undefined;
+}
+/**
+ * Build the SEO graph from route declarations and content collections.
+ *
+ * Synchronous: the caller materializes its collections before calling, so there is
+ * no async work here. Callers own the origin.
+ */
+declare function buildSeoGraph(input: BuildSeoGraphInput): SeoGraph;
+//#endregion
+export { SeoGraph as a, SeoNodeHead as c, buildSeoGraph as d, SeoEdgeType as i, SeoRouteNode as l, SeoCollection as n, SeoInstance as o, SeoEdge as r, SeoNode as s, BuildSeoGraphInput as t, SeoSource as u };
+//# sourceMappingURL=graph-BxCY90vq.d.ts.map

package/dist/graph-CBIY71w6.d.ts

@@ -0,0 +1,57 @@
+import { a as SeoGraph } from "./graph-BxCY90vq.js";
+import { r as RobotsConfig } from "./projections-DeEFe7XT.js";
+import { t as SeoRouteConfigOptions } from "./route-config-wneg6ktn.js";
+import "@tanstack/router-generator";
+//#region src/tanstack-start/graph.d.ts
+/** The robots.txt policy a build serves; `origin` and indexability come from {@link SiteRuntime}. */
+type RobotsPolicy = Pick<RobotsConfig, "disallow" | "contentSignal" | "directives">;
+/** The graph and the site runtime one evaluation produces. */
+interface AppGraph {
+  readonly graph: SeoGraph;
+  readonly site: SiteRuntime;
+}
+/** Site identity and robots policy, baked into the runtime module per build. */
+interface SiteRuntime {
+  readonly origin: string;
+  readonly indexable: boolean;
+  readonly robots: RobotsPolicy;
+}
+interface PagegraphOptions {
+  /** This build's canonical origin, no trailing slash, e.g. `https://example.com`. */
+  readonly origin: string;
+  /**
+   * Whether this build's host may be indexed. A non-indexable build serves a
+   * disallow-all robots.txt with no Sitemap line. Defaults to `true`.
+   */
+  readonly indexable?: boolean | undefined;
+  readonly robots?: {
+    /** Path prefixes disallowed on an indexable host, beyond the route-config exclusions. */
+    readonly disallow?: ReadonlyArray<string> | undefined;
+    /** `Content-Signal` value for an indexable host, e.g. `"search=yes, ai-input=yes, ai-train=yes"`. */
+    readonly contentSignal?: string | undefined;
+    /** Extra lines in the `User-agent: *` group on an indexable host. */
+    readonly directives?: ReadonlyArray<string> | undefined;
+  } | undefined;
+  /**
+   * Root-relative module whose `collections` export is a `SeoCollection[]`, or a
+   * function returning one (sync or async). It runs in the app's Vite pipeline,
+   * so content virtual modules (Fumadocs, MDX) and path aliases resolve.
+   */
+  readonly collections?: string | undefined;
+  /**
+   * Route files (globs relative to the routes directory) never evaluated for the
+   * graph: app surfaces that declare `staticData` but import server-runtime-only
+   * modules. Their paths stay out of the graph.
+   */
+  readonly exclude?: ReadonlyArray<string> | undefined;
+  /** Relative to the Vite root. Defaults to `src/routes`. */
+  readonly routesDirectory?: string | undefined;
+  /**
+   * Generate the route-config module and enforce per-group SEO coverage (the
+   * `seoRouteConfig` gate). Its robots exclusions join `robots.disallow`.
+   */
+  readonly routeConfig?: Omit<SeoRouteConfigOptions, "routesDirectory"> | undefined;
+}
+//#endregion
+export { SiteRuntime as i, PagegraphOptions as n, RobotsPolicy as r, AppGraph as t };
+//# sourceMappingURL=graph-CBIY71w6.d.ts.map

package/dist/index.d.ts

@@ -1,79 +1,43 @@
-import { $ as PublicPath, A as RenderedEdgeFailure, B as FreshnessEntry, C as Anchor, D as RENDERED_EDGE_ARTIFACT_SCHEMA_VERSION, E as LinkGraphDiff, F as decodeRenderedEdgeArtifact, G as SeoCollection, H as FreshnessReport, I as diffLinkGraph, J as SeoGraph, K as SeoEdge, L as extractAnchors, M as RenderedPage, N as SimpleEdge, O as RenderedEdgeArtifact, P as buildRenderedGraph, Q as buildSeoGraph, R as normalizePath, S as hasStructuralViolations, T as LinkEdge, U as freshnessReport, V as FreshnessPolicy, W as BuildSeoGraphInput, X as SeoNode, Y as SeoInstance, Z as SeoSource, _ as Violation, a as Heading, b as checkGraph, c as RenderedDocument, d as checkRenderedContent, et as Register, f as extractPageContent, g as Severity, h as CoverageRule, i as ContentRuleName, j as RenderedGraph, k as RenderedEdgeArtifactCrawl, l as WordCountRule, m as CheckGraphOptions, n as ContentFinding, nt as SeoKind, o as JsonLdNode, p as renderedCheckTargets, q as SeoEdgeType, r as ContentPolicy, rt as SitemapPolicy, s as PageContent, t as ContentCheckOptions, tt as RouteSeo, u as checkPageContent, v as checkCoverage, w as AnchorRegion, x as checkRenderedCoverage, y as checkFreshness, z as renderedGraphFromEdges } from "./content-DVL2iyGU.js";
+import { a as SeoFaq, c as SitemapPolicy, i as RouteSeo, l as applyTitleTemplate, n as PublicPath, o as SeoKind, r as Register, s as SeoPageHead, t as JsonLdDocument } from "./declare-DVgdEdOL.js";
+import { a as SeoGraph, c as SeoNodeHead, d as buildSeoGraph, i as SeoEdgeType, l as SeoRouteNode, n as SeoCollection, o as SeoInstance, r as SeoEdge, s as SeoNode, t as BuildSeoGraphInput, u as SeoSource } from "./graph-BxCY90vq.js";
+import { A as RenderedEdgeFailure, B as FreshnessEntry, C as Anchor, D as RENDERED_EDGE_ARTIFACT_SCHEMA_VERSION, E as LinkGraphDiff, F as decodeRenderedEdgeArtifact, H as FreshnessReport, I as diffLinkGraph, L as extractAnchors, M as RenderedPage, N as SimpleEdge, O as RenderedEdgeArtifact, P as buildRenderedGraph, R as normalizePath, S as hasStructuralViolations, T as LinkEdge, U as freshnessReport, V as FreshnessPolicy, _ as Violation, a as Heading, b as checkGraph, c as RenderedDocument, d as checkRenderedContent, f as extractPageContent, g as Severity, h as CoverageRule, i as ContentRuleName, j as RenderedGraph, k as RenderedEdgeArtifactCrawl, l as WordCountRule, m as CheckGraphOptions, n as ContentFinding, o as JsonLdNode, p as renderedCheckTargets, r as ContentPolicy, s as PageContent, t as ContentCheckOptions, u as checkPageContent, v as checkCoverage, w as AnchorRegion, x as checkRenderedCoverage, y as checkFreshness, z as renderedGraphFromEdges } from "./content-B1cPtL8b.js";
+import { a as inspectNode, c as renderRobots, i as contentSignal, l as renderSitemap, n as ProjectionConfig, o as isSitemapEligible, r as RobotsConfig, s as lastModified, t as NodeReport } from "./projections-DeEFe7XT.js";
+import { i as selectPageHeadNodes, n as PageHeadsOptions, r as pageHeads, t as PageHead } from "./page-heads-DNkjMUEN.js";
 import { AnyRouter } from "@tanstack/react-router";
-//#region src/core/projections.d.ts
-interface ProjectionConfig {
-  origin: string;
-  indexable: boolean;
+//#region src/core/collections.d.ts
+/** What a page contributes: its instance metadata plus the paths it links to deliberately. */
+interface ContentEntry extends Omit<SeoInstance, "path"> {
+  /** Defaults to the page's `url`. */
+  readonly path?: string | undefined;
+  /** Deliberate cross-links, emitted as `related` edges from this page. */
+  readonly related?: ReadonlyArray<string> | undefined;
 }
-interface RobotsConfig extends ProjectionConfig {
-  /** Path prefixes to disallow on an indexable host (e.g. the app-only groups). */
-  disallow: ReadonlyArray<string>;
-  /**
-   * Origin-wide Content-Signal preferences
-   * (https://contentsignals.org/), emitted as `Content-Signal: <value>` under
-   * `User-agent: *` on an indexable host. Omit for none. The plugin never
-   * invents a default — pass the policy you want, e.g.
-   * `"search=yes, ai-input=yes, ai-train=yes"`.
-   */
-  contentSignal?: string | undefined;
-  /**
-   * Extra full lines in the indexable `User-agent: *` group, after
-   * Content-Signal (if any) and before Allow/Disallow. Use for directives the
-   * plugin does not model, or to compose {@link contentSignal} yourself.
-   */
-  directives?: ReadonlyArray<string> | undefined;
-  /**
-   * Last-mile override: receives the rendered robots.txt and returns the file
-   * to emit. Runs for indexable and preview hosts. Use when you need to wrap
-   * or replace the default body rather than add group lines.
-   */
-  transform?: ((robots: string) => string) | undefined;
+interface ContentCollectionOptions<Page> {
+  /** The param route these pages render through, e.g. `/blog/$slug`. */
+  readonly route: PublicPath;
+  /** The `source` label stamped on every node, e.g. `"blog"`. */
+  readonly source: SeoSource;
+  readonly pages: ReadonlyArray<Page>;
+  /** Map one page to its entry; decode frontmatter here. */
+  readonly entry: (page: Page) => ContentEntry;
+  /** Edges beyond `related` (crumb parents, collection membership). */
+  readonly edges?: ReadonlyArray<SeoEdge> | undefined;
 }
-interface NodeReport {
-  node: SeoNode;
-  inSitemap: boolean;
-  incoming: Array<SeoEdge>;
-  outgoing: Array<SeoEdge>;
+declare function contentCollection<Page extends {
+  readonly url: string;
+}>(options: ContentCollectionOptions<Page>): SeoCollection;
+//#endregion
+//#region src/core/wire.d.ts
+interface SeoGraphJson {
+  readonly nodes: ReadonlyArray<SeoNode>;
+  readonly edges: ReadonlyArray<SeoEdge>;
+  readonly collisions?: ReadonlyArray<{
+    readonly path: string;
+    readonly sources: ReadonlyArray<SeoSource>;
+  }> | undefined;
 }
-/**
- * A node belongs in the sitemap when it declares a positive sitemap policy, is not
- * a redirect, is not robots-noindexed, and is not a param template (a route whose
- * path still contains a `$` segment — those exist only so their instances inherit).
- */
-declare function isSitemapEligible(node: SeoNode): boolean;
-/**
- * The date a node's content last changed, as declared: an instance's
- * `modifiedAt`, else its `publishedAt`; a route's own `modifiedAt`. A node with
- * no date (a docs page without frontmatter dates, an undated route) returns
- * undefined, and the sitemap omits its `<lastmod>`.
- */
-declare function lastModified(node: SeoNode): string | undefined;
-/**
- * Render sitemap.xml from the graph. Each entry's `<lastmod>` is its
- * {@link lastModified} date: frontmatter for content instances, the declared
- * `modifiedAt` for routes. Route entries are sorted by path, then instances follow in collection order.
- * `indexable` is intentionally unused — the sitemap body is host-independent;
- * robots.txt is what gates crawling.
- */
-declare function renderSitemap(graph: SeoGraph, cfg: ProjectionConfig): string;
-/** Format a Content-Signal robots.txt directive from the preference list. */
-declare function contentSignal(value: string): string;
-/**
- * Render robots.txt. A non-indexable host (previews) gets a disallow-all
- * with no Sitemap line; an indexable host disallows exactly the prefixes the caller
- * passes. Pages that declare `robots: noindex` are intentionally NOT added as
- * Disallow entries — a Disallow would stop crawlers reaching the page to read its
- * `noindex, follow` meta, so the graph's per-node robots policy never feeds this
- * list. `graph` is unused — kept for signature parity with the other projections,
- * which callers load the graph once for and pass to each.
- *
- * Origin-wide group directives (`contentSignal`, `directives`) are indexable-host
- * only. {@link RobotsConfig.transform} always runs last so a consumer can override
- * the whole file.
- */
-declare function renderRobots(_graph: SeoGraph, cfg: RobotsConfig): string;
-/** Inspect a single node: its declaration, sitemap eligibility, and edges. */
-declare function inspectNode(graph: SeoGraph, path: string): NodeReport | undefined;
+declare function graphToJson(graph: SeoGraph): SeoGraphJson;
+declare function graphFromJson(json: SeoGraphJson): SeoGraph;
 //#endregion
 //#region src/core/link-candidates.d.ts
 /** One proposed contextual link, in the direction the link would be authored. */
@@ -192,5 +156,5 @@ declare const hasBlockingIssues: (report: LiveHeadReport) => boolean;
  */
 declare function resolveRouteLink(router: AnyRouter, path: string): RouteSeo["link"];
 //#endregion
-export { type Anchor, type AnchorRegion, type BuildSeoGraphInput, type CheckGraphOptions, type ContentCheckOptions, type ContentFinding, type ContentPolicy, type ContentRuleName, type CoverageRule, type FreshnessEntry, type FreshnessPolicy, type FreshnessReport, type Heading, type JsonLdNode, type JsonLdReport, type LinkCandidateOptions, type LinkCandidatePair, type LinkCandidateResult, type LinkClusterSummary, type LinkEdge, type LinkGraphDiff, type LiveHeadReport, type NodeReport, type PageContent, type ProjectionConfig, type PublicPath, RENDERED_EDGE_ARTIFACT_SCHEMA_VERSION, type Register, type RenderedDocument, type RenderedEdgeArtifact, type RenderedEdgeArtifactCrawl, type RenderedEdgeFailure, type RenderedGraph, type RenderedPage, type RobotsConfig, type RouteSeo, type SeoCollection, type SeoEdge, type SeoEdgeType, type SeoGraph, type SeoInstance, type SeoKind, type SeoNode, type SeoSource, type Severity, type SimpleEdge, type SitemapPolicy, type Violation, type WordCountRule, buildRenderedGraph, buildSeoGraph, candidateSourceText, checkCoverage, checkFreshness, checkGraph, checkPageContent, checkRenderedContent, checkRenderedCoverage, contentSignal, decodeRenderedEdgeArtifact, decodeRenderedEdges, diffLinkGraph, extractAnchors, extractPageContent, freshnessReport, generateLinkCandidates, hasBlockingIssues, hasStructuralViolations, inspectHtml, inspectNode, isSitemapEligible, lastModified, matchesClusterFilter, normalizePath, renderRobots, renderSitemap, renderedCheckTargets, renderedGraphFromEdges, resolveRouteLink, undirectedEdgeKey };
+export { type Anchor, type AnchorRegion, type BuildSeoGraphInput, type CheckGraphOptions, type ContentCheckOptions, type ContentCollectionOptions, type ContentEntry, type ContentFinding, type ContentPolicy, type ContentRuleName, type CoverageRule, type FreshnessEntry, type FreshnessPolicy, type FreshnessReport, type Heading, type JsonLdDocument, type JsonLdNode, type JsonLdReport, type LinkCandidateOptions, type LinkCandidatePair, type LinkCandidateResult, type LinkClusterSummary, type LinkEdge, type LinkGraphDiff, type LiveHeadReport, type NodeReport, type PageContent, type PageHead, type PageHeadsOptions, type ProjectionConfig, type PublicPath, RENDERED_EDGE_ARTIFACT_SCHEMA_VERSION, type Register, type RenderedDocument, type RenderedEdgeArtifact, type RenderedEdgeArtifactCrawl, type RenderedEdgeFailure, type RenderedGraph, type RenderedPage, type RobotsConfig, type RouteSeo, type SeoCollection, type SeoEdge, type SeoEdgeType, type SeoFaq, type SeoGraph, type SeoGraphJson, type SeoInstance, type SeoKind, type SeoNode, type SeoNodeHead, type SeoPageHead, type SeoRouteNode, type SeoSource, type Severity, type SimpleEdge, type SitemapPolicy, type Violation, type WordCountRule, applyTitleTemplate, buildRenderedGraph, buildSeoGraph, candidateSourceText, checkCoverage, checkFreshness, checkGraph, checkPageContent, checkRenderedContent, checkRenderedCoverage, contentCollection, contentSignal, decodeRenderedEdgeArtifact, decodeRenderedEdges, diffLinkGraph, extractAnchors, extractPageContent, freshnessReport, generateLinkCandidates, graphFromJson, graphToJson, hasBlockingIssues, hasStructuralViolations, inspectHtml, inspectNode, isSitemapEligible, lastModified, matchesClusterFilter, normalizePath, pageHeads, renderRobots, renderSitemap, renderedCheckTargets, renderedGraphFromEdges, resolveRouteLink, selectPageHeadNodes, undirectedEdgeKey };
 //# sourceMappingURL=index.d.ts.map