@riebeckite/core 0.0.1 → 0.0.3

package/dist/index.d.ts

@@ -19,6 +19,7 @@ export { ContentManager } from "./src/content/content_manager.js";
 export { extractFrontmatterAliases } from "./src/content/content_metadata.js";
 export type { ContentSource, ContentSourceContent, ContentSourceEntry, ContentSourceMetadata, } from "./src/content/content_source.js";
 export { getContentSourceEntry, readContentSourceEntry, } from "./src/content/content_source.js";
+export { resolveContentStableId } from "./src/content/content_stable_id.js";
 export { FileSystemContentSource } from "./src/content/file_system_content_source.js";
 export { IMAGE_EXTENSIONS } from "./src/content/image_extensions.js";
 export { readOnlyContentGraph } from "./src/content/read_only_content_graph.js";
@@ -30,19 +31,21 @@ export type { LogContext, Logger, LogLevel, Observability, ObservabilityValue, T
 export { CompositeTraceSink, ConsoleLogger, NoopLogger, NoopTracer, SinkTracer, } from "./src/observability.js";
 export type { PipelineOptions } from "./src/pipeline.js";
 export { Pipeline } from "./src/pipeline.js";
-export type { JsonValue, PluginCache } from "./src/plugin/plugin_cache.js";
+export type { JsonValue } from "./src/types/json_value.js";
+export type { PluginCache } from "./src/plugin/plugin_cache.js";
 export type { CreatePluginMemoOptions, PluginMemo, } from "./src/plugin/plugin_memo.js";
 export { createPluginMemo, stableStringify, } from "./src/plugin/plugin_memo.js";
 export { PluginDependencyError, type PluginDependencyErrorKind, } from "./src/plugin/plugin_dependency_error.js";
 export type { ConfigValidationIssue, PluginOptionsValidator, } from "./src/types/config_validation.js";
-export type { ContentAsset, ContentLink, ContentLinkKind, ContentLocationInput, ContentManifest, ContentManifestEntry, ContentPublicLocation, ContentRedirect, } from "./src/types/content_manifest.js";
+export type { ContentAsset, ContentBodySlot, ContentLink, ContentLinkKind, ContentLocationInput, ContentManifest, ContentManifestEntry, ContentManifestPluginClientEntry, ContentPublicLocation, ContentRedirect, } from "./src/types/content_manifest.js";
+export { appendContentBodySlot } from "./src/types/content_manifest.js";
 export type { Diagnostic, DiagnosticCode, DiagnosticSeverity, } from "./src/types/diagnostic.js";
 export type { GeneratedOutput, GeneratedOutputContent, GeneratedOutputInput, GeneratedOutputSink, } from "./src/types/generated_output.js";
 export { createUnavailableGeneratedOutputSink, normalizeGeneratedOutputPath, } from "./src/types/generated_output.js";
 export type { PluginInput, ResolvedPluginMetadata, RiebeckitePlugin, } from "./src/types/plugin.js";
 export { definePlugin, getResolvedPluginMetadata, resolvePlugins, } from "./src/types/plugin.js";
 export type { PluginAsset, PluginAssetKind, PluginClientEntry, } from "./src/types/plugin_asset.js";
-export { createClientEntry, createStyleAsset, } from "./src/types/plugin_asset.js";
+export { createClientEntry, createStyleAsset, serializePublicClientConfig, } from "./src/types/plugin_asset.js";
 export type { PluginContentContext, PluginContentLocationAugmentContext, PluginContentLocationContext, PluginContentLocationResolver, PluginContentRenderer, PluginContext, PluginGeneratedHtml, PluginGeneratedHtmlInspector, PluginGraphContext, PluginLifecycleContext, PluginManifestContext, PluginPostContext, PluginRenderContext, PluginRenderInput, PluginRenderTarget, } from "./src/types/plugin_context.js";
 export type { PluginDiagnostic, PluginDiagnosticLevel, } from "./src/types/plugin_diagnostic.js";
 export type { PluginHeadTag } from "./src/types/plugin_head.js";

package/dist/index.js

@@ -1749,6 +1749,55 @@ function escapeRegExp(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 
+// src/types/plugin_asset.ts
+function createStyleAsset(pluginName) {
+  return {
+    pluginName,
+    kind: "style",
+    moduleSpecifier: `@riebeckite/plugin-${pluginName}/style.css`
+  };
+}
+function createClientEntry(pluginName, exportName, publicConfig) {
+  return {
+    pluginName,
+    moduleSpecifier: `@riebeckite/plugin-${pluginName}/client`,
+    ...exportName === void 0 ? {} : { exportName },
+    ...publicConfig === void 0 ? {} : { publicConfig }
+  };
+}
+function serializePublicClientConfig(value) {
+  assertJsonValue(value, /* @__PURE__ */ new Set());
+  return JSON.stringify(value);
+}
+function assertJsonValue(value, ancestors) {
+  if (value === null || typeof value === "boolean" || typeof value === "string") {
+    return;
+  }
+  if (typeof value === "number") {
+    if (Number.isFinite(value)) return;
+    throw new TypeError("Public client configuration numbers must be finite.");
+  }
+  if (typeof value !== "object") {
+    throw new TypeError(
+      "Public client configuration must be JSON-serializable."
+    );
+  }
+  if (ancestors.has(value)) {
+    throw new TypeError("Public client configuration must not contain cycles.");
+  }
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null && !Array.isArray(value)) {
+    throw new TypeError(
+      "Public client configuration must contain only plain objects."
+    );
+  }
+  ancestors.add(value);
+  for (const item of Array.isArray(value) ? value : Object.values(value)) {
+    assertJsonValue(item, ancestors);
+  }
+  ancestors.delete(value);
+}
+
 // src/plugin/plugin_lifecycle.ts
 var PluginLifecycleError = class extends Error {
   constructor(pluginName, hookName, cause) {
@@ -1921,6 +1970,21 @@ var PluginRuntime = class {
       }))
     );
   }
+  /**
+   * Returns browser entries with only explicitly registered public
+   * configuration. Validation occurs here as well as in integrations so a
+   * manifest can safely be serialized by a future static HTML host.
+   */
+  collectClientEntries() {
+    return this.plugins().flatMap(
+      (plugin) => (plugin.clientEntries ?? []).map((entry) => {
+        if (entry.publicConfig !== void 0) {
+          serializePublicClientConfig(entry.publicConfig);
+        }
+        return entry;
+      })
+    );
+  }
   /** Returns registered outputs sorted by path for a deterministic build. */
   collectGeneratedOutputs() {
     return [...this.generatedOutputs].sort(
@@ -2520,6 +2584,34 @@ function linkKind(value) {
   return "note";
 }
 
+// src/content/content_stable_id.ts
+var MAX_STABLE_CONTENT_ID_LENGTH = 160;
+function resolveContentStableId(frontmatter) {
+  const id = readOptionalStableId(frontmatter.id, "id");
+  const uid = readOptionalStableId(frontmatter.uid, "uid");
+  if (id !== void 0 && uid !== void 0 && id !== uid) {
+    throw new Error(
+      'Content frontmatter fields "id" and "uid" must have the same value.'
+    );
+  }
+  return id ?? uid;
+}
+function readOptionalStableId(value, field) {
+  if (value === void 0) return void 0;
+  if (typeof value !== "string") {
+    throw new Error(`Content frontmatter field "${field}" must be a string.`);
+  }
+  if (value.length === 0 || value.length > MAX_STABLE_CONTENT_ID_LENGTH || value.trim() !== value || [...value].some((character) => {
+    const code = character.codePointAt(0) ?? 0;
+    return code <= 31 || code === 127;
+  })) {
+    throw new Error(
+      `Content frontmatter field "${field}" must be a non-empty, trimmed string of at most ${MAX_STABLE_CONTENT_ID_LENGTH} characters without control characters.`
+    );
+  }
+  return value;
+}
+
 // src/content/manifest_builder.ts
 var ManifestBuilder = class {
   createEntry(slug, markdown, processed, contentIndex, location) {
@@ -2527,8 +2619,10 @@ var ManifestBuilder = class {
     const assets = links.filter(
       (link) => (link.kind === "image" || link.kind === "attachment") && link.slug !== null
     ).map((link) => ({ path: link.slug }));
+    const contentId = resolveContentStableId(processed.frontmatter);
     return {
       slug,
+      ...contentId === void 0 ? {} : { contentId },
       permalink: location.permalink,
       publicLocation: location,
       title: getManifestTitle(slug, processed.frontmatter.title),
@@ -2545,6 +2639,7 @@ var ManifestBuilder = class {
   }
   build(entries, contentIndex) {
     const bySlug = new Map(entries.map((entry) => [entry.slug, entry]));
+    const byContentId = createContentIdIndex(entries);
     const byPermalink = new Map(
       entries.map((entry) => [entry.permalink, entry])
     );
@@ -2570,6 +2665,7 @@ var ManifestBuilder = class {
       entries,
       publicEntries: [...entries],
       bySlug,
+      byContentId,
       byPermalink,
       redirects: /* @__PURE__ */ new Map(),
       publicRedirects: /* @__PURE__ */ new Map(),
@@ -2579,12 +2675,27 @@ var ManifestBuilder = class {
       incomingLinks,
       contentIndex,
       assets: [],
+      clientEntries: [],
       diagnostics: [],
       generatedOutputs: []
     };
     return { ...manifest, graph: createContentGraph(manifest) };
   }
 };
+function createContentIdIndex(entries) {
+  const byContentId = /* @__PURE__ */ new Map();
+  for (const entry of entries) {
+    if (!entry.contentId) continue;
+    const existing = byContentId.get(entry.contentId);
+    if (existing) {
+      throw new Error(
+        `Duplicate content ID "${entry.contentId}" for "${existing.slug}" and "${entry.slug}".`
+      );
+    }
+    byContentId.set(entry.contentId, entry);
+  }
+  return byContentId;
+}
 function getManifestTitle(slug, title) {
   return typeof title === "string" && title.trim() ? title : slug;
 }
@@ -2767,6 +2878,7 @@ var ContentManager = class {
         await this.pluginRuntime.runManifestCreated(manifest, contentIndex);
         this.applyPublicView(manifest);
         manifest.assets = this.pluginRuntime.collectAssets();
+        manifest.clientEntries = this.pluginRuntime.collectClientEntries();
         manifest.diagnostics = [
           ...this.pluginRuntime.getDiagnostics(),
           ...await this.pluginRuntime.collectDiagnostics(contentIndex)
@@ -2800,7 +2912,11 @@ var ContentManager = class {
   async inspect() {
     const [entries, contentIndex] = await Promise.all([
       this.entryReader.getEntries(),
-      this.getContentIndex()
+      this.getContentIndex(),
+      // Location resolution is the generic phase where plugins can inspect all
+      // content entries (including their frontmatter) and register diagnostics.
+      // Run it for inspect/doctor as well as for a full manifest build.
+      this.getContentLocations()
     ]);
     const diagnostics = await this.pluginRuntime.collectDiagnostics(contentIndex);
     return { entries, contentIndex, diagnostics };
@@ -2943,19 +3059,14 @@ function warn(logger, message, key, error) {
   });
 }
 
-// src/types/plugin_asset.ts
-function createStyleAsset(pluginName) {
-  return {
-    pluginName,
-    kind: "style",
-    moduleSpecifier: `@riebeckite/plugin-${pluginName}/style.css`
-  };
-}
-function createClientEntry(pluginName, exportName) {
-  return {
-    pluginName,
-    moduleSpecifier: `@riebeckite/plugin-${pluginName}/client`,
-    ...exportName === void 0 ? {} : { exportName }
+// src/types/content_manifest.ts
+function appendContentBodySlot(entry, slot, html) {
+  if (!html.trim()) return;
+  const previous = entry.bodySlots?.[slot];
+  entry.bodySlots = {
+    ...entry.bodySlots,
+    [slot]: previous ? `${previous}
+${html}` : html
   };
 }
 
@@ -2991,6 +3102,7 @@ export {
   Pipeline,
   PluginDependencyError,
   SinkTracer,
+  appendContentBodySlot,
   attachmentUrl,
   buildContentCollections,
   buildGraphEdges,
@@ -3032,8 +3144,10 @@ export {
   resolveConfigModule,
   resolveContentBuildStatePath,
   resolveContentQueryPagination,
+  resolveContentStableId,
   resolveDefaultContentLocation,
   resolvePlugins,
+  serializePublicClientConfig,
   stableStringify,
   stripHtml,
   uniqueStrings

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

@@ -0,0 +1,8 @@
+import type { PostFrontmatter } from "../types/post_content.js";
+/**
+ * Reads the optional, source-authored stable content ID.
+ *
+ * `id` is the canonical frontmatter field. `uid` is accepted only for
+ * compatibility with existing content that used it before `id` was standard.
+ */
+export declare function resolveContentStableId(frontmatter: PostFrontmatter): string | undefined;

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

@@ -1,8 +1,7 @@
 import type { Logger, Tracer } from "../observability.js";
+import type { JsonValue } from "../types/json_value.js";
 import type { ResolvedRiebeckiteConfig } from "../types/resolved_riebeckite_config.js";
-export type JsonValue = null | boolean | number | string | JsonValue[] | {
-    [key: string]: JsonValue;
-};
+export type { JsonValue } from "../types/json_value.js";
 export type PluginCache = {
     get<T extends JsonValue>(key: string): Promise<T | undefined>;
     set<T extends JsonValue>(key: string, value: T): Promise<void>;
@@ -19,4 +18,3 @@ type CreatePluginCacheOptions = {
 };
 export declare function createPluginCache(options: CreatePluginCacheOptions): PluginCache;
 export declare function resolvePluginCacheDirectory(config: ResolvedRiebeckiteConfig | undefined): string;
-export {};

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

@@ -2,6 +2,7 @@ import type { PipelineOptions } from "../pipeline.js";
 import type { ContentLocationInput, ContentManifest, ContentManifestEntry, ContentPublicLocation } from "../types/content_manifest.js";
 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 { PostContent } from "../types/post_content.js";
 /**
  * Explicit build lifecycle stages. `idle` means no build lifecycle has been
@@ -45,6 +46,12 @@ export declare class PluginRuntime {
         kind: import("../types/plugin_asset.js").PluginAssetKind;
         moduleSpecifier: string;
     }[];
+    /**
+     * Returns browser entries with only explicitly registered public
+     * configuration. Validation occurs here as well as in integrations so a
+     * manifest can safely be serialized by a future static HTML host.
+     */
+    collectClientEntries(): PluginClientEntry[];
     /** Returns registered outputs sorted by path for a deterministic build. */
     collectGeneratedOutputs(): GeneratedOutput[];
     collectDiagnostics(contentIndex: Map<string, string>): Promise<Diagnostic[]>;

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

@@ -1,7 +1,7 @@
 import type { ContentGraph } from "../content/content_graph.js";
 import type { Diagnostic } from "./diagnostic.js";
 import type { GeneratedOutput } from "./generated_output.js";
-import type { PluginAsset } from "./plugin_asset.js";
+import type { PluginAsset, PluginClientEntry } from "./plugin_asset.js";
 import type { PluginHeadTag } from "./plugin_head.js";
 import type { PostFrontmatter } from "./post_content.js";
 export type ContentLinkKind = "note" | "image" | "attachment" | "unresolved";
@@ -17,8 +17,22 @@ export type ContentAsset = {
 export type ContentManifestPluginAsset = PluginAsset & {
     path: string;
 };
+/**
+ * A semantic position in a Site-owned article layout.
+ *
+ * The standard article consumer recognizes the `article.*` positions below.
+ * Other names remain valid so a custom Site can define its own layout slots.
+ */
+export type ContentBodySlot = "article.after-header" | "article.after-meta" | "article.before-content" | "article.after-content" | "article.footer" | (string & {});
+/** Client entries and their explicitly public configuration. */
+export type ContentManifestPluginClientEntry = PluginClientEntry;
 export type ContentManifestEntry = {
     slug: string;
+    /**
+     * Optional source-authored stable content identity. It is independent of the
+     * slug, permalink, aliases, and redirects.
+     */
+    contentId?: string;
     permalink: string;
     publicLocation: ContentPublicLocation;
     title: string;
@@ -40,6 +54,13 @@ export type ContentManifestEntry = {
     backlinks: string[];
     assets: ContentAsset[];
 };
+/**
+ * Appends a Plugin-provided HTML fragment to a named Site layout slot.
+ *
+ * Plugins publish fragments; the Site chooses which slots to render and where.
+ * Appending preserves contributions from earlier plugins in resolved order.
+ */
+export declare function appendContentBodySlot(entry: ContentManifestEntry, slot: ContentBodySlot, html: string): void;
 export type ContentRedirect = {
     path: string;
     status: 301 | 302 | 307 | 308;
@@ -64,6 +85,8 @@ export type ContentManifest = {
      */
     publicEntries: ContentManifestEntry[];
     bySlug: Map<string, ContentManifestEntry>;
+    /** Contains only entries with an explicit source-authored content ID. */
+    byContentId: Map<string, ContentManifestEntry>;
     byPermalink: Map<string, ContentManifestEntry>;
     redirects: Map<string, ContentRedirect & {
         slug: string;
@@ -82,6 +105,11 @@ export type ContentManifest = {
     contentIndex: Map<string, string>;
     graph: ContentGraph;
     assets: ContentManifestPluginAsset[];
+    /**
+     * Browser entries registered by plugins. This contains only each entry's
+     * explicit `publicConfig`, never the plugin's complete `options` object.
+     */
+    clientEntries: ContentManifestPluginClientEntry[];
     diagnostics: Diagnostic[];
     generatedOutputs: GeneratedOutput[];
 };

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

@@ -0,0 +1,4 @@
+/** A value that can be represented without loss in JSON. */
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};

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

@@ -1,13 +1,28 @@
+import type { JsonValue } from "./json_value.js";
 export type PluginAssetKind = "style" | "script";
 export type PluginAsset = {
     pluginName: string;
     kind: PluginAssetKind;
     moduleSpecifier: string;
 };
-export type PluginClientEntry = {
+export type PluginClientEntry<TPublicConfig extends JsonValue = JsonValue> = {
     pluginName: string;
     moduleSpecifier: string;
     exportName?: string;
+    /**
+     * Configuration intentionally made available to this browser entry.
+     *
+     * Plugin `options` are never inferred or copied here. Only this value is
+     * included in client-facing output, so it must not contain secrets or other
+     * private build-time options.
+     */
+    publicConfig?: TPublicConfig;
 };
 export declare function createStyleAsset(pluginName: string): PluginAsset;
-export declare function createClientEntry(pluginName: string, exportName?: string): PluginClientEntry;
+export declare function createClientEntry<TPublicConfig extends JsonValue>(pluginName: string, exportName?: string, publicConfig?: TPublicConfig): PluginClientEntry<TPublicConfig>;
+/**
+ * Serializes explicitly registered client configuration for code generation.
+ * Rejecting non-JSON values prevents generated client modules from silently
+ * dropping or changing configuration supplied through an untyped plugin.
+ */
+export declare function serializePublicClientConfig(value: unknown): string;

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

@@ -3,6 +3,13 @@ export type PostContent = {
     html: string;
 };
 export type PostFrontmatter = Record<string, unknown> & {
+    /**
+     * Optional source-authored stable content identity. Unlike a slug or URL,
+     * this value survives a rename or public-location change.
+     */
+    id?: string;
+    /** @deprecated Use `id`. Read only as a compatibility fallback. */
+    uid?: string;
     title?: string;
     description?: string;
     date?: string | Date;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@riebeckite/core",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "license": "Apache-2.0",
   "type": "module",
   "main": "./dist/index.js",