@riebeckite/core 0.0.12 → 0.0.14

package/README.md

@@ -1,94 +1,94 @@
-# @riebeckite/core
-
-The portable framework contract for Riebeckite: configuration, content sources,
-the content manager, the Markdown/HTML pipeline, plugin and theme contracts,
-diagnostics, and observability.
-
-[日本語](./README_ja.md)
-
-## Overview
-
-`@riebeckite/core` owns content loading and interpretation and the contracts
-that extensions build against. It is intentionally free of HonoX, Vite, and any
-specific plugin, theme, or application: those depend on Core, never the reverse.
-
-A site configures Core through `defineConfig`, and a framework integration such
-as [`@riebeckite/honox`](../integrations/honox/README.md) drives the build.
-Plugins and themes are plain objects created by `definePlugin` and `defineTheme`.
-
-## Installation
-
-```sh
-pnpm add @riebeckite/core
-```
-
-Core is also installed transitively by `@riebeckite/honox` and by the
-`@riebeckite/plugin-*` and `@riebeckite/theme-*` packages.
-
-## Usage
-
-```ts
-import { defineConfig } from "@riebeckite/core";
-
-export default defineConfig({
-  site: { title: "My notes", baseUrl: "https://example.com" },
-  content: { directory: "../../content" },
-});
-```
-
-The content directory is resolved relative to the application root. See
-[Configuration](../../docs/en/configuration.md) for the full field list and the
-`projectRoot` / `appRoot` / `configRoot` / `contentRoot` resolution rules.
-
-## Public API
-
-### Configuration
-
-- `defineConfig`, `resolveConfig`, `resolveConfigModule`, `isPublished`,
-  `isExcluded`
-- `ConfigValidationError`
-
-### Content
-
-- `ContentManager` — interpretation, manifest, graph, plugin orchestration, and
-  public-location resolution
-- `ContentSource`, `FileSystemContentSource`, `readContentSourceEntry`,
-  `getContentSourceEntry`
-- `queryContentEntries` with the `ContentQuery*` filter and sort types
-- `createContentGraph`, `readOnlyContentGraph`, `buildGraphEdges`,
-  `layoutRadialGraph`
-- `resolveDefaultContentLocation`, `attachmentUrl`, and the content path and
-  extension helpers
-- `readContentBuildStateStatus`, `resolveContentBuildStatePath`
-
-### Pipeline
-
-- `Pipeline`, `PipelineOptions`
-
-### Plugins
-
-- `definePlugin`, `resolvePlugins`, `getResolvedPluginMetadata`,
-  `PluginDependencyError`
-- `defineEndpoint`, `createClientEntry`, `createStyleAsset`
-- Plugin context, asset, endpoint, diagnostic, SEO, and pipeline types under
-  `Plugin*`
-
-### Themes and contracts
-
-- `defineTheme` and the `Theme*` types
-- `RiebeckiteConfig`, `ResolvedRiebeckiteConfig`, `SiteConfig`,
-  `PostContent`, `PostFrontmatter`, `PublishStrategy`
-
-### Utilities and observability
-
-- `uniqueStrings`, `escapeHtml`, `escapeHtmlAttribute`, `normalizeTag`,
-  `calculateReadingTime`, `stripHtml`
-- `ConsoleLogger`, `NoopLogger`, `NoopTracer`, `SinkTracer`,
-  `CompositeTraceSink`
-
-## See also
-
-- [Framework Reference](../../docs/en/framework-reference.md)
-- [Content System](../../docs/en/content-system.md)
-- [Plugin System](../../docs/en/plugin-system.md) / [Theme System](../../docs/en/theme-system.md)
-- [Architecture](../../docs/en/architecture.md)
+# @riebeckite/core
+
+The portable framework contract for Riebeckite: configuration, content sources,
+the content manager, the Markdown/HTML pipeline, plugin and theme contracts,
+diagnostics, and observability.
+
+[日本語](./README_ja.md)
+
+## Overview
+
+`@riebeckite/core` owns content loading and interpretation and the contracts
+that extensions build against. It is intentionally free of HonoX, Vite, and any
+specific plugin, theme, or application: those depend on Core, never the reverse.
+
+A site configures Core through `defineConfig`, and a framework integration such
+as [`@riebeckite/honox`](../integrations/honox/README.md) drives the build.
+Plugins and themes are plain objects created by `definePlugin` and `defineTheme`.
+
+## Installation
+
+```sh
+pnpm add @riebeckite/core
+```
+
+Core is also installed transitively by `@riebeckite/honox` and by the
+`@riebeckite/plugin-*` and `@riebeckite/theme-*` packages.
+
+## Usage
+
+```ts
+import { defineConfig } from "@riebeckite/core";
+
+export default defineConfig({
+  site: { title: "My notes", baseUrl: "https://example.com" },
+  content: { directory: "../../content" },
+});
+```
+
+The content directory is resolved relative to the application root. See
+[Configuration](../../docs/en/reference/configuration.md) for the full field list and the
+`projectRoot` / `appRoot` / `configRoot` / `contentRoot` resolution rules.
+
+## Public API
+
+### Configuration
+
+- `defineConfig`, `resolveConfig`, `resolveConfigModule`, `isPublished`,
+  `isExcluded`
+- `ConfigValidationError`
+
+### Content
+
+- `ContentManager` — interpretation, manifest, graph, plugin orchestration, and
+  public-location resolution
+- `ContentSource`, `FileSystemContentSource`, `readContentSourceEntry`,
+  `getContentSourceEntry`
+- `queryContentEntries` with the `ContentQuery*` filter and sort types
+- `createContentGraph`, `readOnlyContentGraph`, `buildGraphEdges`,
+  `layoutRadialGraph`
+- `resolveDefaultContentLocation`, `attachmentUrl`, and the content path and
+  extension helpers
+- `readContentBuildStateStatus`, `resolveContentBuildStatePath`
+
+### Pipeline
+
+- `Pipeline`, `PipelineOptions`
+
+### Plugins
+
+- `definePlugin`, `resolvePlugins`, `getResolvedPluginMetadata`,
+  `PluginDependencyError`
+- `defineEndpoint`, `createClientEntry`, `createStyleAsset`
+- Plugin context, asset, endpoint, diagnostic, SEO, and pipeline types under
+  `Plugin*`
+
+### Themes and contracts
+
+- `defineTheme` and the `Theme*` types
+- `RiebeckiteConfig`, `ResolvedRiebeckiteConfig`, `SiteConfig`,
+  `PostContent`, `PostFrontmatter`, `PublishStrategy`
+
+### Utilities and observability
+
+- `uniqueStrings`, `escapeHtml`, `escapeHtmlAttribute`, `normalizeTag`,
+  `calculateReadingTime`, `stripHtml`
+- `ConsoleLogger`, `NoopLogger`, `NoopTracer`, `SinkTracer`,
+  `CompositeTraceSink`
+
+## See also
+
+- [Framework Reference](../../docs/en/reference/README.md)
+- [Content System](../../docs/en/framework/content-system.md)
+- [Plugin System](../../docs/en/reference/plugin-api.md) / [Theme System](../../docs/en/reference/theme-api.md)
+- [Architecture](../../docs/en/framework/architecture.md)

package/README_ja.md

@@ -1,75 +1,75 @@
-# @riebeckite/core
-
-Riebeckite の移植可能なフレームワーク契約です。設定、コンテンツソース、ContentManager、Markdown/HTML パイプライン、Plugin と Theme の契約、診断、可観測性を担います。
-
-[English](./README.md)
-
-## 概要
-
-`@riebeckite/core` はコンテンツの読み込みと解釈、および拡張が依存する契約を所有します。HonoX や Vite、特定の Plugin・Theme・アプリケーションには依存しません。依存の向きは常に Core へ向かい、その逆には向かいません。
-
-サイトは `defineConfig` で Core を設定し、[`@riebeckite/honox`](../integrations/honox/README_ja.md) のような integration がビルドを実行します。Plugin と Theme は `definePlugin`、`defineTheme` が返すただのオブジェクトです。
-
-## インストール
-
-```sh
-pnpm add @riebeckite/core
-```
-
-`@riebeckite/honox`、`@riebeckite/plugin-*`、`@riebeckite/theme-*` をインストールすると、依存として一緒に入ります。
-
-## 使い方
-
-```ts
-import { defineConfig } from "@riebeckite/core";
-
-export default defineConfig({
-  site: { title: "My notes", baseUrl: "https://example.com" },
-  content: { directory: "../../content" },
-});
-```
-
-コンテンツディレクトリはアプリケーションルート基準で解決します。設定項目の全体と `projectRoot` / `appRoot` / `configRoot` / `contentRoot` の解決規則は [Configuration](../../docs/ja/configuration.md) を参照してください。
-
-## 公開 API
-
-### 設定
-
-- `defineConfig`、`resolveConfig`、`resolveConfigModule`、`isPublished`、`isExcluded`
-- `ConfigValidationError`
-
-### コンテンツ
-
-- `ContentManager` — 解釈、マニフェスト、グラフ、Plugin の実行、公開 URL の解決
-- `ContentSource`、`FileSystemContentSource`、`readContentSourceEntry`、`getContentSourceEntry`
-- `queryContentEntries` と `ContentQuery*` のフィルタ・ソート型
-- `createContentGraph`、`readOnlyContentGraph`、`buildGraphEdges`、`layoutRadialGraph`
-- `resolveDefaultContentLocation`、`attachmentUrl`、コンテンツパスと拡張子のヘルパー
-- `readContentBuildStateStatus`、`resolveContentBuildStatePath`
-
-### パイプライン
-
-- `Pipeline`、`PipelineOptions`
-
-### Plugin
-
-- `definePlugin`、`resolvePlugins`、`getResolvedPluginMetadata`、`PluginDependencyError`
-- `defineEndpoint`、`createClientEntry`、`createStyleAsset`
-- `Plugin*` のコンテキスト、アセット、エンドポイント、診断、SEO、パイプラインの型
-
-### Theme と契約
-
-- `defineTheme` と `Theme*` の型
-- `RiebeckiteConfig`、`ResolvedRiebeckiteConfig`、`SiteConfig`、`PostContent`、`PostFrontmatter`、`PublishStrategy`
-
-### ユーティリティと可観測性
-
-- `uniqueStrings`、`escapeHtml`、`escapeHtmlAttribute`、`normalizeTag`、`calculateReadingTime`、`stripHtml`
-- `ConsoleLogger`、`NoopLogger`、`NoopTracer`、`SinkTracer`、`CompositeTraceSink`
-
-## 関連資料
-
-- [Framework Reference](../../docs/ja/framework-reference.md)
-- [Content System](../../docs/ja/content-system.md)
-- [Plugin System](../../docs/ja/plugin-system.md) / [Theme System](../../docs/ja/theme-system.md)
-- [Architecture](../../docs/ja/architecture.md)
+# @riebeckite/core
+
+Riebeckite の移植可能なフレームワーク契約です。設定、コンテンツソース、ContentManager、Markdown/HTML パイプライン、Plugin と Theme の契約、診断、可観測性を担います。
+
+[English](./README.md)
+
+## 概要
+
+`@riebeckite/core` はコンテンツの読み込みと解釈、および拡張が依存する契約を所有します。HonoX や Vite、特定の Plugin・Theme・アプリケーションには依存しません。依存の向きは常に Core へ向かい、その逆には向かいません。
+
+サイトは `defineConfig` で Core を設定し、[`@riebeckite/honox`](../integrations/honox/README_ja.md) のような integration がビルドを実行します。Plugin と Theme は `definePlugin`、`defineTheme` が返すただのオブジェクトです。
+
+## インストール
+
+```sh
+pnpm add @riebeckite/core
+```
+
+`@riebeckite/honox`、`@riebeckite/plugin-*`、`@riebeckite/theme-*` をインストールすると、依存として一緒に入ります。
+
+## 使い方
+
+```ts
+import { defineConfig } from "@riebeckite/core";
+
+export default defineConfig({
+  site: { title: "My notes", baseUrl: "https://example.com" },
+  content: { directory: "../../content" },
+});
+```
+
+コンテンツディレクトリはアプリケーションルート基準で解決します。設定項目の全体と `projectRoot` / `appRoot` / `configRoot` / `contentRoot` の解決規則は [Configuration](../../docs/ja/reference/configuration.md) を参照してください。
+
+## 公開 API
+
+### 設定
+
+- `defineConfig`、`resolveConfig`、`resolveConfigModule`、`isPublished`、`isExcluded`
+- `ConfigValidationError`
+
+### コンテンツ
+
+- `ContentManager` — 解釈、マニフェスト、グラフ、Plugin の実行、公開 URL の解決
+- `ContentSource`、`FileSystemContentSource`、`readContentSourceEntry`、`getContentSourceEntry`
+- `queryContentEntries` と `ContentQuery*` のフィルタ・ソート型
+- `createContentGraph`、`readOnlyContentGraph`、`buildGraphEdges`、`layoutRadialGraph`
+- `resolveDefaultContentLocation`、`attachmentUrl`、コンテンツパスと拡張子のヘルパー
+- `readContentBuildStateStatus`、`resolveContentBuildStatePath`
+
+### パイプライン
+
+- `Pipeline`、`PipelineOptions`
+
+### Plugin
+
+- `definePlugin`、`resolvePlugins`、`getResolvedPluginMetadata`、`PluginDependencyError`
+- `defineEndpoint`、`createClientEntry`、`createStyleAsset`
+- `Plugin*` のコンテキスト、アセット、エンドポイント、診断、SEO、パイプラインの型
+
+### Theme と契約
+
+- `defineTheme` と `Theme*` の型
+- `RiebeckiteConfig`、`ResolvedRiebeckiteConfig`、`SiteConfig`、`PostContent`、`PostFrontmatter`、`PublishStrategy`
+
+### ユーティリティと可観測性
+
+- `uniqueStrings`、`escapeHtml`、`escapeHtmlAttribute`、`normalizeTag`、`calculateReadingTime`、`stripHtml`
+- `ConsoleLogger`、`NoopLogger`、`NoopTracer`、`SinkTracer`、`CompositeTraceSink`
+
+## 関連資料
+
+- [Framework Reference](../../docs/ja/reference/README.md)
+- [Content System](../../docs/ja/framework/content-system.md)
+- [Plugin System](../../docs/ja/reference/plugin-api.md) / [Theme System](../../docs/ja/reference/theme-api.md)
+- [Architecture](../../docs/ja/framework/architecture.md)

package/dist/client.d.ts

@@ -0,0 +1,2 @@
+export type { GraphEdge, GraphLayoutNode, LinkableGraphNode, RadialGraphLayoutOptions, } from "./src/content/graph_layout.js";
+export { buildGraphEdges, layoutRadialGraph, } from "./src/content/graph_layout.js";

package/dist/client.js

@@ -0,0 +1,43 @@
+// src/content/graph_layout.ts
+function buildGraphEdges(nodes, visibleSlugs = new Set(nodes.map((node) => node.slug))) {
+  const edges = /* @__PURE__ */ new Map();
+  for (const node of nodes) {
+    for (const target of node.outgoing) {
+      if (!visibleSlugs.has(node.slug) || !visibleSlugs.has(target)) continue;
+      const key = `${node.slug}\0${target}`;
+      edges.set(key, { source: node.slug, target });
+    }
+  }
+  return Array.from(edges.values());
+}
+function layoutRadialGraph(nodes, options) {
+  const layout = /* @__PURE__ */ new Map();
+  const centerX = options.width / 2;
+  const centerY = options.height / 2;
+  const radius = Math.min(options.width, options.height) * (options.radiusRatio ?? 0.36);
+  const minNodeRadius = options.minNodeRadius ?? 8;
+  const maxNodeRadius = options.maxNodeRadius ?? 14;
+  const selectedIndex = Math.max(
+    nodes.findIndex((node) => node.slug === options.centerSlug),
+    0
+  );
+  nodes.forEach((node, index) => {
+    const shiftedIndex = (index - selectedIndex + nodes.length) % nodes.length;
+    const angle = shiftedIndex / Math.max(nodes.length, 1) * Math.PI * 2;
+    const linkCount = node.outgoing.length + node.backlinks.length;
+    const isCenter = node.slug === options.centerSlug;
+    layout.set(node.slug, {
+      x: isCenter ? centerX : centerX + Math.cos(angle) * radius,
+      y: isCenter ? centerY : centerY + Math.sin(angle) * radius,
+      radius: clamp(7 + linkCount, minNodeRadius, maxNodeRadius)
+    });
+  });
+  return layout;
+}
+function clamp(value, min, max) {
+  return Math.min(Math.max(value, min), max);
+}
+export {
+  buildGraphEdges,
+  layoutRadialGraph
+};

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { defineConfig, isExcluded, isPublished, resolveConfig, resolveConfigModule, } from "./src/config.js";
+export { type ConfigDeprecationNotice, collectConfigDeprecationDiagnostics, } from "./src/config_deprecations.js";
 export { ConfigValidationError } from "./src/config_validation.js";
 export { ATTACHMENTS_BASE_PATH, attachmentUrl, getExtension, isAttachmentPath, isImagePath, isMarkdownPath, normalizeContentPath, } from "./src/content/attachment.js";
 export type { ContentBuildState, FingerprintedContentEntry, } from "./src/content/content_build_state.js";
@@ -23,6 +24,7 @@ export type { GraphEdge, GraphLayoutNode, LinkableGraphNode, RadialGraphLayoutOp
 export { buildGraphEdges, layoutRadialGraph, } from "./src/content/graph_layout.js";
 export { IMAGE_EXTENSIONS } from "./src/content/image_extensions.js";
 export { readOnlyContentGraph } from "./src/content/read_only_content_graph.js";
+export { createDeprecationDiagnostic, type DeprecationKind, type DeprecationNotice, formatDeprecationMessage, } from "./src/deprecation.js";
 export type { LogContext, Logger, LogLevel, Observability, ObservabilityValue, TraceAttributes, TraceEvent, Tracer, TraceSink, TraceSpan, } from "./src/observability.js";
 export { CompositeTraceSink, ConsoleLogger, NoopLogger, NoopTracer, SinkTracer, } from "./src/observability.js";
 export type { PipelineOptions } from "./src/pipeline.js";
@@ -47,6 +49,7 @@ export type { PluginDiagnostic, PluginDiagnosticLevel, } from "./src/types/plugi
 export type { PluginEndpoint, PluginEndpointContext, PluginEndpointMethod, PluginEndpointOptions, PluginEndpointRequest, PluginEndpointResponse, } from "./src/types/plugin_endpoint.js";
 export { defineEndpoint } from "./src/types/plugin_endpoint.js";
 export type { PluginHeadTag } from "./src/types/plugin_head.js";
+export type { PluginPage, PluginPageContext, PluginPageType, ResolvedPluginPage, } from "./src/types/plugin_page.js";
 export type { HtmlPipeline, MarkdownEmbedFragment, MarkdownExecutionContext, MarkdownPipeline, MarkdownPipelineContext, PipelinePlugin, } from "./src/types/plugin_pipeline.js";
 export type { PluginSeoExtension, RenderableFeedEntry, SeoMetadata, WebsiteSeoInput, } from "./src/types/plugin_seo.js";
 export type { PostContent, PostFrontmatter } from "./src/types/post_content.js";

package/dist/index.js

@@ -693,6 +693,46 @@ function globToRegExp(glob) {
   return new RegExp(`^${re}$`);
 }
 
+// src/deprecation.ts
+function createDeprecationDiagnostic(notice) {
+  return {
+    code: `deprecated-${notice.kind}`,
+    severity: "warning",
+    message: formatDeprecationMessage(notice),
+    target: notice.target,
+    suggestion: notice.replacement ? `Use ${notice.replacement}. ${notice.action}` : notice.action,
+    meta: { deprecation: notice }
+  };
+}
+function formatDeprecationMessage(notice) {
+  const lines = [
+    `Deprecated: ${notice.target}`,
+    `Deprecated since: ${notice.deprecatedSince}`
+  ];
+  if (notice.replacement) lines.push(`Use: ${notice.replacement}`);
+  lines.push(`Migration: ${notice.action}`);
+  if (notice.documentationUrl) lines.push(`See: ${notice.documentationUrl}`);
+  if (notice.removedIn) lines.push(`Removal planned: ${notice.removedIn}`);
+  return lines.join("\n");
+}
+
+// src/config_deprecations.ts
+var configDeprecations = [];
+function collectConfigDeprecationDiagnostics(config, notices = configDeprecations) {
+  return notices.filter((notice) => hasConfigPath(config, notice.path)).map(createDeprecationDiagnostic);
+}
+function hasConfigPath(config, path4) {
+  let value = config;
+  for (const segment of path4.split(".")) {
+    if (!isRecord2(value) || !(segment in value)) return false;
+    value = value[segment];
+  }
+  return value !== void 0;
+}
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
 // src/content/image_extensions.ts
 var IMAGE_EXTENSIONS = [
   "png",
@@ -770,7 +810,7 @@ async function readContentBuildStateStatus(statePath) {
     }
     throw error;
   }
-  if (!isRecord2(parsed)) {
+  if (!isRecord3(parsed)) {
     return { kind: "invalid", path: statePath, reason: "invalid-shape" };
   }
   if (parsed.version !== CONTENT_BUILD_STATE_VERSION) {
@@ -810,19 +850,19 @@ function resolveContentBuildStatePath(config, contentDirectory) {
   );
 }
 function isContentBuildState(value) {
-  return isRecord2(value) && value.version === CONTENT_BUILD_STATE_VERSION && isContentBuildStateShape(value);
+  return isRecord3(value) && value.version === CONTENT_BUILD_STATE_VERSION && isContentBuildStateShape(value);
 }
 function isContentBuildStateShape(value) {
-  if (!isRecord2(value.entries) || !isRecord2(value.contentIndex)) return false;
+  if (!isRecord3(value.entries) || !isRecord3(value.contentIndex)) return false;
   return Object.values(value.entries).every(
-    (entry) => isRecord2(entry) && typeof entry.fingerprint === "string" && entry.fingerprint.length > 0 && Array.isArray(entry.dependencies) && entry.dependencies.every(
+    (entry) => isRecord3(entry) && typeof entry.fingerprint === "string" && entry.fingerprint.length > 0 && Array.isArray(entry.dependencies) && entry.dependencies.every(
       (dependency) => typeof dependency === "string"
     )
   ) && Object.values(value.contentIndex).every(
     (entry) => typeof entry === "string"
   );
 }
-function isRecord2(value) {
+function isRecord3(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function isNotFoundError(error) {
@@ -1588,6 +1628,7 @@ var Pipeline = class {
         markdownPipelineContext
       );
     }
+    this.use(processor, normalizeMarkdownLinks, markdownPipelineContext);
     this.use(processor, remarkRehype, { allowDangerousHtml: true });
     this.use(processor, rehypeRaw);
     for (const plugin of plugins) {
@@ -1701,6 +1742,81 @@ function selectBlockFragment(markdown, blockId) {
   const line = lines.find((currentLine) => blockIdRe.test(currentLine));
   return line?.replace(blockIdRe, "").trimEnd() || null;
 }
+function normalizeMarkdownLinks(context) {
+  return (tree) => {
+    visitMarkdownLinkNodes(tree, (node) => {
+      const normalizedUrl = normalizeMarkdownLinkUrl(node.url, context);
+      if (normalizedUrl) node.url = normalizedUrl;
+    });
+  };
+}
+function visitMarkdownLinkNodes(node, visitor) {
+  const linkNode = node;
+  if ((node.type === "link" || node.type === "definition") && typeof linkNode.url === "string") {
+    visitor(linkNode);
+  }
+  for (const child of linkNode.children ?? []) {
+    visitMarkdownLinkNodes(child, visitor);
+  }
+}
+function normalizeMarkdownLinkUrl(url, context) {
+  if (!context.sourceSlug) return null;
+  if (!isMarkdownContentLink(url)) return null;
+  const [pathAndQuery, hash3 = ""] = splitOnce(url, "#");
+  const [rawPath, query = ""] = splitOnce(pathAndQuery, "?");
+  const decodedPath = decodeUriPath(rawPath);
+  if (!decodedPath?.toLowerCase().endsWith(".md")) return null;
+  const resolvedSlug = resolveRelativeMarkdownSlug(
+    context.sourceSlug,
+    decodedPath
+  );
+  if (!resolvedSlug) return null;
+  const indexedSlug = getExactContentSlug(context, resolvedSlug);
+  if (!indexedSlug) return null;
+  const suffix = `${query ? `?${query}` : ""}${hash3 ? `#${hash3}` : ""}`;
+  return `${context.resolvePermalink(indexedSlug)}${suffix}`;
+}
+function getExactContentSlug(context, slug) {
+  try {
+    context.resolvePermalink(slug);
+    return slug;
+  } catch {
+    return context.contentIndex.get(slug.toLowerCase()) ?? null;
+  }
+}
+function isMarkdownContentLink(url) {
+  if (url.startsWith("#") || url.startsWith("//")) return false;
+  if (/^[a-z][a-z0-9+.-]*:/i.test(url)) return false;
+  return true;
+}
+function resolveRelativeMarkdownSlug(sourceSlug, targetPath) {
+  const sourceDirectory = sourceSlug.includes("/") ? sourceSlug.slice(0, sourceSlug.lastIndexOf("/")) : "";
+  const baseParts = targetPath.startsWith("/") ? [] : sourceDirectory.split("/");
+  const parts = [...baseParts, ...targetPath.replace(/^\/+/, "").split("/")];
+  const normalizedParts = [];
+  for (const part of parts) {
+    if (!part || part === ".") continue;
+    if (part === "..") {
+      if (normalizedParts.length === 0) return null;
+      normalizedParts.pop();
+      continue;
+    }
+    normalizedParts.push(part);
+  }
+  return normalizedParts.join("/").replace(/\.md$/i, "");
+}
+function decodeUriPath(path4) {
+  try {
+    return decodeURI(path4);
+  } catch {
+    return null;
+  }
+}
+function splitOnce(value, separator) {
+  const index = value.indexOf(separator);
+  if (index < 0) return [value];
+  return [value.slice(0, index), value.slice(index + separator.length)];
+}
 function selectHeadingFragment(markdown, heading) {
   const lines = markdown.split(/\r?\n/);
   const targetHeading = heading.trim().toLowerCase();
@@ -1990,6 +2106,53 @@ var PluginRuntime = class {
   collectGeneratedOutputs() {
     return this.generatedOutputs.all();
   }
+  async resolvePage(pathname, manifest, contentIndex) {
+    const matches = [];
+    const normalizedPathname = normalizePagePath(pathname);
+    const context = {
+      ...this.createContext(contentIndex),
+      manifest,
+      pathname: normalizedPathname
+    };
+    for (const plugin of this.plugins()) {
+      for (const pageType of plugin.pageTypes ?? []) {
+        const page = await pageType.resolve(
+          this.createPluginContext(plugin, context)
+        );
+        if (page) {
+          matches.push({
+            page: { ...page, type: pageType.id, pluginName: plugin.name },
+            priority: pageType.priority ?? 0
+          });
+        }
+      }
+    }
+    if (matches.length === 0) return null;
+    const highestPriority = Math.max(...matches.map((match) => match.priority));
+    const highest = matches.filter(
+      (match) => match.priority === highestPriority
+    );
+    if (highest.length !== 1) {
+      throw new Error(
+        `Multiple plugin page types match ${normalizedPathname} at priority ${highestPriority}: ${highest.map((match) => match.page.type).join(", ")}`
+      );
+    }
+    return highest[0].page;
+  }
+  async getPagePaths(manifest, contentIndex) {
+    const paths = [];
+    const context = { ...this.createContext(contentIndex), manifest };
+    for (const plugin of this.plugins()) {
+      for (const pageType of plugin.pageTypes ?? []) {
+        const declared = pageType.paths;
+        if (!declared) continue;
+        paths.push(
+          ...typeof declared === "function" ? await declared(this.createPluginContext(plugin, context)) : declared
+        );
+      }
+    }
+    return [...new Set(paths.map(normalizePagePath))];
+  }
   async collectDiagnostics(contentIndex) {
     const tracer = this.observability().tracer;
     return await tracer.span("diagnostics.run", {}, async () => {
@@ -2095,9 +2258,57 @@ var PluginRuntime = class {
     return this.pipelineOptions.observability ?? noopObservability;
   }
   plugins() {
-    return resolvePlugins(this.pipelineOptions.plugins);
+    const plugins = resolvePlugins(this.pipelineOptions.plugins);
+    const pageTypes = /* @__PURE__ */ new Map();
+    for (const plugin of plugins) {
+      const declaredPageTypes = plugin.pageTypes;
+      if (declaredPageTypes !== void 0 && !Array.isArray(declaredPageTypes)) {
+        throw new TypeError(`Plugin ${plugin.name} pageTypes must be an array`);
+      }
+      for (const pageType of declaredPageTypes ?? []) {
+        validatePageType(plugin.name, pageType);
+        const previous = pageTypes.get(pageType.id);
+        if (previous) {
+          throw new Error(
+            `Plugin page type "${pageType.id}" is provided by both ${previous} and ${plugin.name}`
+          );
+        }
+        pageTypes.set(pageType.id, plugin.name);
+      }
+    }
+    return plugins;
   }
 };
+function validatePageType(pluginName, pageType) {
+  if (typeof pageType !== "object" || pageType === null) {
+    throw new TypeError(`Plugin ${pluginName} pageTypes must contain objects`);
+  }
+  const candidate = pageType;
+  if (typeof candidate.id !== "string" || candidate.id.trim() === "") {
+    throw new TypeError(
+      `Plugin ${pluginName} page type id must be a non-empty string`
+    );
+  }
+  if (typeof candidate.resolve !== "function") {
+    throw new TypeError(
+      `Plugin ${pluginName} page type "${candidate.id}" must provide a resolve function`
+    );
+  }
+  if (candidate.paths !== void 0 && !Array.isArray(candidate.paths) && typeof candidate.paths !== "function") {
+    throw new TypeError(
+      `Plugin ${pluginName} page type "${candidate.id}" paths must be an array or function`
+    );
+  }
+  if (candidate.priority !== void 0 && (typeof candidate.priority !== "number" || !Number.isFinite(candidate.priority))) {
+    throw new TypeError(
+      `Plugin ${pluginName} page type "${candidate.id}" priority must be a finite number`
+    );
+  }
+}
+function normalizePagePath(pathname) {
+  const path4 = `/${pathname.split("/").filter(Boolean).join("/")}`;
+  return path4 === "/" ? path4 : path4.replace(/\/$/, "");
+}
 function countSeverity(diagnostics, severity) {
   return diagnostics.filter((diagnostic) => diagnostic.severity === severity).length;
 }
@@ -2660,7 +2871,8 @@ var ManifestBuilder = class {
       assets: [],
       clientEntries: [],
       diagnostics: [],
-      generatedOutputs: []
+      generatedOutputs: [],
+      pagePaths: []
     };
     return { ...manifest, graph: createContentGraph(manifest) };
   }
@@ -2680,7 +2892,10 @@ function createContentIdIndex(entries) {
   return byContentId;
 }
 function getManifestTitle(slug, title) {
-  return typeof title === "string" && title.trim() ? title : slug;
+  if (typeof title === "string" && title.trim()) {
+    return title.trim();
+  }
+  return slug.split("/").at(-1) ?? slug;
 }
 function uniqueAssets(assets) {
   return Array.from(
@@ -2858,6 +3073,9 @@ var ContentManager = class {
         this.locationResolver.populateRedirects(manifest, locations);
         await this.pluginRuntime.runManifestCreated(manifest, contentIndex);
         this.applyPublicView(manifest);
+        manifest.pagePaths = [
+          ...await this.pluginRuntime.getPagePaths(manifest, contentIndex)
+        ];
         manifest.assets = this.pluginRuntime.collectAssets();
         manifest.clientEntries = this.pluginRuntime.collectClientEntries();
         manifest.diagnostics = [
@@ -2890,6 +3108,26 @@ var ContentManager = class {
     const manifest = await this.getManifest();
     return manifest.diagnostics;
   }
+  /** Resolves a page contributed by an enabled plugin. */
+  async resolvePage(pathname) {
+    const [manifest, contentIndex] = await Promise.all([
+      this.getManifest(),
+      this.getContentIndex()
+    ]);
+    return await this.pluginRuntime.resolvePage(
+      pathname,
+      manifest,
+      contentIndex
+    );
+  }
+  /** Returns plugin page paths for SSG enumeration. */
+  async getPagePaths() {
+    const [manifest, contentIndex] = await Promise.all([
+      this.getManifest(),
+      this.getContentIndex()
+    ]);
+    return await this.pluginRuntime.getPagePaths(manifest, contentIndex);
+  }
   async inspect() {
     const [entries, contentIndex] = await Promise.all([
       this.entryReader.getEntries(),
@@ -3139,8 +3377,10 @@ export {
   buildContentCollections,
   buildGraphEdges,
   calculateReadingTime,
+  collectConfigDeprecationDiagnostics,
   createClientEntry,
   createContentGraph,
+  createDeprecationDiagnostic,
   createPluginMemo,
   createStyleAsset,
   createUnavailableGeneratedOutputSink,
@@ -3153,6 +3393,7 @@ export {
   escapeScriptJson,
   extractFrontmatterAliases,
   fingerprintContentEntries,
+  formatDeprecationMessage,
   getContentSourceEntry,
   getExtension,
   getResolvedPluginMetadata,

package/dist/src/config_deprecations.d.ts

@@ -0,0 +1,8 @@
+import { type DeprecationNotice } from "./deprecation.js";
+import type { Diagnostic } from "./types/diagnostic.js";
+import type { RiebeckiteConfig } from "./types/riebeckite_config.js";
+export type ConfigDeprecationNotice = DeprecationNotice & {
+    readonly kind: "config";
+    readonly path: string;
+};
+export declare function collectConfigDeprecationDiagnostics(config: RiebeckiteConfig, notices?: readonly ConfigDeprecationNotice[]): Diagnostic[];

package/dist/src/content/content_manager.d.ts

@@ -1,6 +1,7 @@
 import type { PipelineOptions } from "../pipeline.js";
 import type { ContentManifest, ContentPublicLocation } from "../types/content_manifest.js";
 import type { Diagnostic } from "../types/diagnostic.js";
+import type { ResolvedPluginPage } from "../types/plugin_page.js";
 import type { PostContent } from "../types/post_content.js";
 import type { ResolvedRiebeckiteConfig } from "../types/resolved_riebeckite_config.js";
 import { type ContentBuildPreparation } from "./content_build_coordinator.js";
@@ -45,6 +46,10 @@ export declare class ContentManager {
     getBacklinks(targetSlug: string): Promise<Backlink[]>;
     getContentGraph(): Promise<ContentGraph>;
     getDiagnostics(): Promise<Diagnostic[]>;
+    /** Resolves a page contributed by an enabled plugin. */
+    resolvePage(pathname: string): Promise<ResolvedPluginPage | null>;
+    /** Returns plugin page paths for SSG enumeration. */
+    getPagePaths(): Promise<readonly string[]>;
     inspect(): Promise<ContentInspection>;
     dispose(): Promise<void>;
     getContentLocations(): Promise<ReadonlyMap<string, ContentPublicLocation>>;

package/dist/src/deprecation.d.ts

@@ -0,0 +1,14 @@
+import type { Diagnostic } from "./types/diagnostic.js";
+export type DeprecationKind = "config" | "plugin-api" | "theme-api" | "cli" | "scaffold" | "package";
+export type DeprecationNotice = {
+    readonly kind: DeprecationKind;
+    readonly id: string;
+    readonly target: string;
+    readonly deprecatedSince: string;
+    readonly action: string;
+    readonly replacement?: string;
+    readonly documentationUrl?: string;
+    readonly removedIn?: string;
+};
+export declare function createDeprecationDiagnostic(notice: DeprecationNotice): Diagnostic;
+export declare function formatDeprecationMessage(notice: DeprecationNotice): string;

package/dist/src/plugin/plugin_runtime.d.ts

@@ -3,6 +3,7 @@ import type { ContentLocationInput, ContentManifest, ContentManifestEntry, Conte
 import type { Diagnostic } from "../types/diagnostic.js";
 import type { GeneratedOutput } from "../types/generated_output.js";
 import { type PluginClientEntry } from "../types/plugin_asset.js";
+import type { ResolvedPluginPage } from "../types/plugin_page.js";
 import type { PostContent } from "../types/post_content.js";
 /**
  * Explicit build lifecycle stages. `idle` means no build lifecycle has been
@@ -53,6 +54,8 @@ export declare class PluginRuntime {
     collectClientEntries(): PluginClientEntry[];
     /** Returns registered outputs sorted by path for a deterministic build. */
     collectGeneratedOutputs(): GeneratedOutput[];
+    resolvePage(pathname: string, manifest: ContentManifest, contentIndex: Map<string, string>): Promise<ResolvedPluginPage | null>;
+    getPagePaths(manifest: ContentManifest, contentIndex: Map<string, string>): Promise<readonly string[]>;
     collectDiagnostics(contentIndex: Map<string, string>): Promise<Diagnostic[]>;
     private runBuildLifecycle;
     private createContext;

package/dist/src/types/content_manifest.d.ts

@@ -112,4 +112,5 @@ export type ContentManifest = {
     clientEntries: ContentManifestPluginClientEntry[];
     diagnostics: Diagnostic[];
     generatedOutputs: GeneratedOutput[];
+    pagePaths: string[];
 };

package/dist/src/types/plugin.d.ts

@@ -3,6 +3,7 @@ import type { Diagnostic } from "./diagnostic.js";
 import type { PluginAsset, PluginClientEntry } from "./plugin_asset.js";
 import type { PluginContentContext, PluginContentLocationAugmentContext, PluginContentLocationResolver, PluginContentRenderer, PluginContext, PluginGeneratedHtmlInspector, PluginGraphContext, PluginLifecycleContext, PluginManifestContext, PluginPostContext } from "./plugin_context.js";
 import type { PluginEndpoint } from "./plugin_endpoint.js";
+import type { PluginPageType } from "./plugin_page.js";
 import type { HtmlPipeline, MarkdownPipeline, MarkdownPipelineContext, PipelinePlugin } from "./plugin_pipeline.js";
 import type { PluginSeoExtension } from "./plugin_seo.js";
 export type RiebeckitePlugin<TOptions = unknown> = {
@@ -57,6 +58,8 @@ export type RiebeckitePlugin<TOptions = unknown> = {
     seo?: PluginSeoExtension;
     extendContentGraph?(context: PluginGraphContext): void | Promise<void>;
     renderers?: PluginContentRenderer[];
+    /** Framework-independent page types contributed by this plugin. */
+    pageTypes?: PluginPageType[];
 };
 export type PluginInput = RiebeckitePlugin | false | null | undefined;
 export type ResolvedPluginMetadata = {

package/dist/src/types/plugin_page.d.ts

@@ -0,0 +1,36 @@
+import type { ContentManifest } from "./content_manifest.js";
+import type { PluginContext } from "./plugin_context.js";
+import type { PluginHeadTag } from "./plugin_head.js";
+/** A framework-independent page supplied by a Riebeckite plugin. */
+export type PluginPage = {
+    /** Stable identifier of the page type that produced this page. */
+    type: string;
+    /** Canonical, absolute URL path. */
+    pathname: string;
+    /** HTML for the page body. The site owns the surrounding document frame. */
+    body: string;
+    title?: string;
+    description?: string;
+    /** Optional document metadata rendered by the site's document frame. */
+    headTags?: readonly PluginHeadTag[];
+};
+export type PluginPageContext = PluginContext & {
+    /** The public manifest. Unpublished content is not exposed through pages. */
+    manifest: ContentManifest;
+    /** Request pathname, normalized to an absolute path. */
+    pathname: string;
+};
+export type PluginPageType = {
+    /** Globally unique, stable page type identifier. */
+    id: string;
+    /** Paths emitted by SSG for this type. */
+    paths?: readonly string[] | ((context: PluginContext & {
+        manifest: ContentManifest;
+    }) => readonly string[] | Promise<readonly string[]>);
+    /** Higher values win when more than one type matches a request. */
+    priority?: number;
+    resolve(context: PluginPageContext): PluginPage | null | Promise<PluginPage | null>;
+};
+export type ResolvedPluginPage = PluginPage & {
+    pluginName: string;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@riebeckite/core",
-  "version": "0.0.12",
+  "version": "0.0.14",
   "license": "Apache-2.0",
   "type": "module",
   "main": "./dist/index.js",
@@ -12,6 +12,12 @@
       "source": "./index.ts",
       "default": "./dist/index.js"
     },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js",
+      "source": "./client.ts",
+      "default": "./dist/client.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -43,7 +49,7 @@
   },
   "devDependencies": {
     "tsx": "^4.22.4",
-    "@riebeckite/test": "0.0.12"
+    "@riebeckite/test": "0.0.14"
   },
   "repository": {
     "type": "git",