nimbus-docs 0.1.5 → 0.1.7

package/dist/schemas.d.ts

@@ -2,9 +2,13 @@ import { z } from "astro/zod";
 import * as astro_content0 from "astro:content";
 
 //#region src/schemas.d.ts
-interface DocSchemaConfig {
-  /** Additional frontmatter fields merged into the default schema. */
-  fields?: Record<string, z.ZodTypeAny>;
+interface DocSchemaConfig<TFields extends Record<string, z.ZodTypeAny> = Record<string, never>> {
+  /**
+   * Additional frontmatter fields merged into the default schema.
+   * Generic-typed so the call-site shape is preserved through to
+   * `entry.data.<field>` access in consumer code.
+   */
+  fields?: TFields;
 }
 /**
  * Build a customizable docs schema. Use this when composing schemas outside
@@ -14,9 +18,141 @@ interface DocSchemaConfig {
  * For typed Astro `image()` fields or per-collection field narrowing, use
  * the richer `defineSchema(ctx => ...)` factory instead.
  */
-declare function defineDocSchema(config?: DocSchemaConfig): z.ZodObject<Readonly<{
-  [k: string]: z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
-}>, z.core.$loose>;
+declare function defineDocSchema<TFields extends Record<string, z.ZodTypeAny> = Record<string, never>>(config?: DocSchemaConfig<TFields>): z.ZodObject<(("prev" | "next" | "title" | "description" | "mode" | "sidebar" | "head" | "banner" | "draft" | "noindex" | "searchable" | "tableOfContents" | "lastUpdated" | "socialImage" | "previousSlug") & keyof TFields extends never ? {
+  title: z.ZodString;
+  description: z.ZodOptional<z.ZodString>;
+  mode: z.ZodDefault<z.ZodEnum<{
+    doc: "doc";
+    custom: "custom";
+  }>>;
+  sidebar: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodObject<{
+    order: z.ZodOptional<z.ZodNumber>;
+    label: z.ZodOptional<z.ZodString>;
+    badge: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+      text: z.ZodString;
+      variant: z.ZodDefault<z.ZodEnum<{
+        success: "success";
+        default: "default";
+        info: "info";
+        note: "note";
+        tip: "tip";
+        warning: "warning";
+        caution: "caution";
+        danger: "danger";
+      }>>;
+    }, z.core.$strip>]>>;
+    hidden: z.ZodOptional<z.ZodBoolean>;
+    hideChildren: z.ZodOptional<z.ZodBoolean>;
+  }, z.core.$strip>]>>;
+  head: z.ZodDefault<z.ZodArray<z.ZodObject<{
+    tag: z.ZodEnum<{
+      meta: "meta";
+      link: "link";
+      script: "script";
+      style: "style";
+    }>;
+    attrs: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    content: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>>>;
+  banner: z.ZodOptional<z.ZodObject<{
+    content: z.ZodString;
+    type: z.ZodOptional<z.ZodEnum<{
+      note: "note";
+      tip: "tip";
+      caution: "caution";
+      danger: "danger";
+    }>>;
+    dismissible: z.ZodOptional<z.ZodObject<{
+      id: z.ZodString;
+      days: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+  }, z.core.$strip>>;
+  draft: z.ZodDefault<z.ZodBoolean>;
+  noindex: z.ZodDefault<z.ZodBoolean>;
+  searchable: z.ZodOptional<z.ZodBoolean>;
+  tableOfContents: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodObject<{
+    minHeadingLevel: z.ZodDefault<z.ZodNumber>;
+    maxHeadingLevel: z.ZodDefault<z.ZodNumber>;
+  }, z.core.$strip>]>>;
+  lastUpdated: z.ZodOptional<z.ZodCoercedDate<unknown>>;
+  socialImage: z.ZodOptional<z.ZodString>;
+  prev: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+    link: z.ZodOptional<z.ZodString>;
+    label: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>, z.ZodLiteral<false>]>>;
+  next: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+    link: z.ZodOptional<z.ZodString>;
+    label: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>, z.ZodLiteral<false>]>>;
+  previousSlug: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+} & { -readonly [P in keyof TFields]: TFields[P] } : ({
+  title: z.ZodString;
+  description: z.ZodOptional<z.ZodString>;
+  mode: z.ZodDefault<z.ZodEnum<{
+    doc: "doc";
+    custom: "custom";
+  }>>;
+  sidebar: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodObject<{
+    order: z.ZodOptional<z.ZodNumber>;
+    label: z.ZodOptional<z.ZodString>;
+    badge: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+      text: z.ZodString;
+      variant: z.ZodDefault<z.ZodEnum<{
+        success: "success";
+        default: "default";
+        info: "info";
+        note: "note";
+        tip: "tip";
+        warning: "warning";
+        caution: "caution";
+        danger: "danger";
+      }>>;
+    }, z.core.$strip>]>>;
+    hidden: z.ZodOptional<z.ZodBoolean>;
+    hideChildren: z.ZodOptional<z.ZodBoolean>;
+  }, z.core.$strip>]>>;
+  head: z.ZodDefault<z.ZodArray<z.ZodObject<{
+    tag: z.ZodEnum<{
+      meta: "meta";
+      link: "link";
+      script: "script";
+      style: "style";
+    }>;
+    attrs: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    content: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>>>;
+  banner: z.ZodOptional<z.ZodObject<{
+    content: z.ZodString;
+    type: z.ZodOptional<z.ZodEnum<{
+      note: "note";
+      tip: "tip";
+      caution: "caution";
+      danger: "danger";
+    }>>;
+    dismissible: z.ZodOptional<z.ZodObject<{
+      id: z.ZodString;
+      days: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+  }, z.core.$strip>>;
+  draft: z.ZodDefault<z.ZodBoolean>;
+  noindex: z.ZodDefault<z.ZodBoolean>;
+  searchable: z.ZodOptional<z.ZodBoolean>;
+  tableOfContents: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodObject<{
+    minHeadingLevel: z.ZodDefault<z.ZodNumber>;
+    maxHeadingLevel: z.ZodDefault<z.ZodNumber>;
+  }, z.core.$strip>]>>;
+  lastUpdated: z.ZodOptional<z.ZodCoercedDate<unknown>>;
+  socialImage: z.ZodOptional<z.ZodString>;
+  prev: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+    link: z.ZodOptional<z.ZodString>;
+    label: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>, z.ZodLiteral<false>]>>;
+  next: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+    link: z.ZodOptional<z.ZodString>;
+    label: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>, z.ZodLiteral<false>]>>;
+  previousSlug: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+} extends infer T_1 extends z.core.util.SomeObject ? { [K in keyof T_1 as K extends keyof TFields ? never : K]: T_1[K] } : never) & { [K_1 in keyof { -readonly [P in keyof TFields]: TFields[P] }]: { -readonly [P in keyof TFields]: TFields[P] }[K_1] }) extends infer T ? { [k in keyof T]: T[k] } : never, z.core.$strip>;
 /**
  * Factory options for `defineSchema`.
  *
@@ -56,13 +192,13 @@ interface DefineSchemaOptions {
  *     }),
  *   };
  */
-declare function defineSchema(factory: (ctx: astro_content0.SchemaContext) => DefineSchemaOptions): (ctx: astro_content0.SchemaContext) => z.ZodObject<Readonly<{
-  [k: string]: z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
-}>, z.core.$loose> | z.ZodIntersection<z.ZodObject<any, z.core.$strip>, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;
-/** Default docs schema. Equivalent to `defineDocSchema()`. */
-declare const docsSchema: z.ZodObject<Readonly<{
+declare function defineSchema(factory: (ctx: astro_content0.SchemaContext) => DefineSchemaOptions): (ctx: astro_content0.SchemaContext) => z.ZodIntersection<z.ZodObject<any, z.core.$strip>, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>> | z.ZodObject<Readonly<{
   [k: string]: z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
 }>, z.core.$loose>;
+/** Default docs schema. Equivalent to `defineDocSchema()`. */
+declare const docsSchema: z.ZodObject<{
+  [x: string]: never;
+}, z.core.$strip>;
 /** Schema for partials (`<Render file="..." />` snippets). */
 declare const partialsSchema: z.ZodDefault<z.ZodObject<{
   params: z.ZodOptional<z.ZodArray<z.ZodString>>;

package/dist/schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schemas.d.ts","names":[],"sources":["../src/schemas.ts"],"mappings":";;;;UAiBiB,eAAA;EA6Oc;EA3O7B,MAAA,GAAS,MAAA,SAAe,CAAA,CAAE,UAAA;AAAA;;;;;;;;;iBA2OZ,eAAA,CAAgB,MAAA,GAAQ,eAAA,GAAoB,CAAA,CAAA,SAAA,CAAA,QAAA;EAAA;;;;;;;;;;;UAkB3C,mBAAA;EACf,MAAA,GAAS,CAAA,CAAE,UAAA;EACX,MAAA,GAAS,MAAA,SAAe,CAAA,CAAE,UAAA;AAAA;AAF5B;;;;;;;;;;;;;;;;;AA+BA;;;;;;;;;AA/BA,iBA+BgB,YAAA,CACd,OAAA,GAAU,GAAA,EADgB,cAAA,CACa,aAAA,KAAkB,mBAAA,IAEjD,GAAA,EAFoE,cAAA,CAEvC,aAAA,KAAa,CAAA,CAAA,SAAA,CAAA,QAAA;EAAA;;;cA8BvC,UAAA,EAAU,CAAA,CAAA,SAAA,CAAA,QAAA;EAAA;;;cAWV,cAAA,EAAc,CAAA,CAAA,UAAA,CAAA,CAAA,CAAA,SAAA;;;;cAad,iBAAA,EAAiB,CAAA,CAAA,SAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAGjB,qBAAA,EAAqB,CAAA,CAAA,SAAA;;;;cAU5B,mBAAA,EAAmB,CAAA,CAAA,SAAA;;;;;;;KAQb,aAAA,GAAgB,CAAA,CAAE,KAAA,QAAa,mBAAA;;cAG9B,gBAAA,EAAgB,CAAA,CAAA,SAAA"}
+{"version":3,"file":"schemas.d.ts","names":[],"sources":["../src/schemas.ts"],"mappings":";;;;UAiBiB,eAAA,iBACC,MAAA,SAAe,CAAA,CAAE,UAAA,IAAc,MAAA;EAAhB;;;;;EAO/B,MAAA,GAAS,OAAA;AAAA;AA2OX;;;;;;;;AAAA,iBAAgB,eAAA,iBACE,MAAA,SAAe,CAAA,CAAE,UAAA,IAAc,MAAA,gBAAA,CAC/C,MAAA,GAAQ,eAAA,CAAgB,OAAA,IAAa,CAAA,CAAA,SAAA,yMAAA,OAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UAyBtB,mBAAA;EACf,MAAA,GAAS,CAAA,CAAE,UAAA;EACX,MAAA,GAAS,MAAA,SAAe,CAAA,CAAE,UAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA6BZ,YAAA,CACd,OAAA,GAAU,GAAA,EADgB,cAAA,CACa,aAAA,KAAkB,mBAAA,IAEjD,GAAA,EAFoE,cAAA,CAEvC,aAAA,KAAa,CAAA,CAAA,eAAA,CAAA,CAAA,CAAA,SAAA,MAAA,CAAA,CAAA,IAAA,CAAA,MAAA,GAAA,CAAA,CAAA,OAAA,mBAAA,CAAA,CAAA,IAAA,CAAA,iBAAA,uBAAA,CAAA,CAAA,SAAA,CAAA,QAAA;EAAA;;;cA8BvC,UAAA,EAAU,CAAA,CAAA,SAAA;EAAA;GAAoB,CAAA,CAAA,IAAA,CAAA,MAAA;;cAW9B,cAAA,EAAc,CAAA,CAAA,UAAA,CAAA,CAAA,CAAA,SAAA;;;;cAad,iBAAA,EAAiB,CAAA,CAAA,SAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAGjB,qBAAA,EAAqB,CAAA,CAAA,SAAA;;;;cAU5B,mBAAA,EAAmB,CAAA,CAAA,SAAA;;;;;;;KAQb,aAAA,GAAgB,CAAA,CAAE,KAAA,QAAa,mBAAA;;cAG9B,gBAAA,EAAgB,CAAA,CAAA,SAAA"}

package/dist/schemas.js

@@ -140,8 +140,7 @@ function baseDocSchema() {
 * the richer `defineSchema(ctx => ...)` factory instead.
 */
 function defineDocSchema(config = {}) {
-	const base = baseDocSchema();
-	return withFrontmatterKeyCheck(config.fields ? base.extend(config.fields) : base);
+	return withFrontmatterKeyCheck(baseDocSchema().extend(config.fields ?? {}));
 }
 /**
 * Build a typed docs schema with access to the Astro `SchemaContext`.

package/dist/schemas.js.map

@@ -1 +1 @@
-{"version":3,"file":"schemas.js","names":[],"sources":["../src/schemas.ts"],"sourcesContent":["/**\n * Content schemas for Nimbus.\n *\n * `docsSchema` is the default frontmatter contract for the `docs` collection.\n * `partialsSchema` is the contract for `<Render file=\"...\" />` partials.\n * `defineDocSchema(config)` returns a customizable schema for advanced users\n *   composing schemas outside the `docsCollection()` factory.\n *\n * Error messages target content authors, not framework developers.\n * Astro 6 ships Zod v4 via `astro/zod`. The v4 API uses a single `error`\n * field on every schema constructor — NOT v3's `required_error` /\n * `invalid_type_error` / `errorMap`.\n */\n\nimport { z } from \"astro/zod\";\nimport { withStrictKeys } from \"./_internal/strict-keys.js\";\n\nexport interface DocSchemaConfig {\n  /** Additional frontmatter fields merged into the default schema. */\n  fields?: Record<string, z.ZodTypeAny>;\n}\n\n// ---------------------------------------------------------------------------\n// Building blocks\n// ---------------------------------------------------------------------------\n\nconst sidebarBadgeSchema = z.union([\n  z.string(),\n  z.object({\n    text: z.string({ error: 'sidebar badge needs a \"text\" field' }),\n    variant: z\n      .enum(\n        [\"default\", \"info\", \"note\", \"success\", \"tip\", \"warning\", \"caution\", \"danger\"],\n        {\n          error:\n            '\"variant\" must be one of: default, info, note, success, tip, warning, caution, danger',\n        },\n      )\n      .default(\"default\"),\n  }),\n]);\n\nconst sidebarSchema = z.object({\n  order: z.number({ error: '\"sidebar.order\" must be a number' }).optional(),\n  label: z.string({ error: '\"sidebar.label\" must be a string' }).optional(),\n  badge: sidebarBadgeSchema.optional(),\n  hidden: z.boolean({ error: '\"sidebar.hidden\" must be true or false' }).optional(),\n  hideChildren: z\n    .boolean({ error: '\"sidebar.hideChildren\" must be true or false' })\n    .optional(),\n});\n\nconst prevNextSchema = z\n  .union([\n    z.string(),\n    z.object({ link: z.string().optional(), label: z.string().optional() }),\n    z.literal(false),\n  ])\n  .optional();\n\nconst headElementSchema = z.object({\n  tag: z.enum([\"meta\", \"link\", \"script\", \"style\"], {\n    error: 'head element \"tag\" must be \"meta\", \"link\", \"script\", or \"style\"',\n  }),\n  attrs: z.record(z.string(), z.string()).default({}),\n  content: z.string().optional(),\n});\n\n// Mirrors `BannerProps` in types.ts. Layouts consume this directly off\n// `entry.data.banner` and render the `<Banner>` component with it, so the\n// schema is framework-owned (not user-extensible territory).\nconst bannerSchema = z.object({\n  content: z.string({ error: 'banner \"content\" must be a string' }),\n  type: z\n    .enum([\"note\", \"tip\", \"caution\", \"danger\"], {\n      error: 'banner \"type\" must be one of: note, tip, caution, danger',\n    })\n    .optional(),\n  dismissible: z\n    .object({\n      id: z.string({\n        error: 'banner \"dismissible.id\" must be a string — a stable identifier you bump when banner content meaningfully changes',\n      }),\n      days: z.number({ error: 'banner \"dismissible.days\" must be a number' }).optional(),\n    })\n    .optional(),\n});\n\n// ---------------------------------------------------------------------------\n// Removed/renamed frontmatter keys — surface migration errors loudly\n// ---------------------------------------------------------------------------\n\n/**\n * Frontmatter keys that used to exist but no longer do. When user content\n * still carries one of these, Zod's default `.strip()` behavior would\n * silently drop it — the page would build, but with subtly different\n * behavior (the old toggle just disappears). That's a confusing failure\n * mode for an authoring contract.\n *\n * `withUnknownKeyCheck` (below) consults this map. Hits get the friendly\n * migration message verbatim; everything else falls through to a generic\n * \"Unknown frontmatter key\" error so typos don't sneak past either.\n *\n * Entries removed in the v0 → v1 cleanup:\n *\n *   - `template` → `mode`: same shape, but `\"splash\"` is now `\"custom\"`.\n *   - `pagefind` → `searchable`: same boolean; default now derives from\n *     `noindex` (a non-crawlable page is non-searchable by default).\n *   - `llms`: removed. All published pages are listed in `/llms.txt`; the\n *     escape hatch is `noindex: true`.\n *   - `aiDeprioritize`: removed. The framework no longer emits an\n *     agent-downrank signal.\n *   - `hero`: removed. Compose the hero in MDX body with user-owned\n *     components instead of a frontmatter contract.\n */\nconst REMOVED_FRONTMATTER_KEYS: Record<string, string> = {\n  template:\n    'was renamed to \"mode\". Replace `template: \"doc\"` with `mode: \"doc\"`, and `template: \"splash\"` with `mode: \"custom\"`.',\n  pagefind:\n    'was renamed to \"searchable\". Same boolean shape; the default now derives from `noindex` (a non-crawlable page is non-searchable unless you set `searchable: true` explicitly).',\n  llms:\n    \"was removed. Every published page is now listed in /llms.txt; use `noindex: true` to keep a page out of both search engines and the LLM index.\",\n  aiDeprioritize:\n    \"was removed. The framework no longer emits an agent-downrank signal. If you want a page hidden from agents, use `noindex: true`.\",\n  hero:\n    \"was removed. Compose your hero in the MDX body using user-owned components; there is no longer a `hero` frontmatter contract.\",\n};\n\n/**\n * Apply this AFTER any `.extend()` so user-added fields are recognized\n * as valid. Wraps the schema in `.passthrough().superRefine()` so removed\n * keys raise a guided migration error; other unknown keys raise a\n * generic error pointing at `defineSchema({ extend: ... })`.\n */\nfunction withFrontmatterKeyCheck<T extends z.ZodObject<z.ZodRawShape>>(schema: T) {\n  return withStrictKeys(schema, {\n    removedKeys: REMOVED_FRONTMATTER_KEYS,\n    contextLabel: \"Frontmatter key\",\n    unknownHint: (key) =>\n      `If you meant to add a custom field, declare it in your collection's schema via \\`defineSchema({ extend: z.object({ ${key}: ... }) })\\`.`,\n  });\n}\n\n// ---------------------------------------------------------------------------\n// Base docs schema\n// ---------------------------------------------------------------------------\n\nfunction baseDocSchema() {\n  return z.object({\n    title: z.string({\n      error: (iss) =>\n        iss.input === undefined\n          ? 'Missing required \"title\" in frontmatter. Every doc needs:\\n\\n  ---\\n  title: \"Your Page Title\"\\n  ---'\n          : `\"title\" must be a string, received ${typeof iss.input}`,\n    }),\n    description: z.string({ error: '\"description\" must be a string' }).optional(),\n    mode: z\n      .enum([\"doc\", \"custom\"], {\n        error: '\"mode\" must be \"doc\" or \"custom\"',\n      })\n      .default(\"doc\"),\n    sidebar: z.union([z.literal(false), sidebarSchema]).optional(),\n    head: z.array(headElementSchema).default([]),\n    banner: bannerSchema.optional(),\n    draft: z.boolean({ error: '\"draft\" must be true or false' }).default(false),\n    noindex: z.boolean({ error: '\"noindex\" must be true or false' }).default(false),\n    /**\n     * Whether this page is included in the site search index. When omitted,\n     * derives from `noindex` (a page that's not crawlable is by default not\n     * searchable). Set explicitly to override — e.g. `{ noindex: true,\n     * searchable: true }` keeps the page out of search engines but findable\n     * in the site's own search.\n     */\n    searchable: z\n      .boolean({ error: '\"searchable\" must be true or false' })\n      .optional(),\n    tableOfContents: z\n      .union([\n        z.literal(false),\n        z\n          .object({\n            minHeadingLevel: z\n              .number({ error: '\"minHeadingLevel\" must be a number (1-6)' })\n              .int()\n              .min(1)\n              .max(6)\n              .default(2),\n            maxHeadingLevel: z\n              .number({ error: '\"maxHeadingLevel\" must be a number (1-6)' })\n              .int()\n              .min(1)\n              .max(6)\n              .default(3),\n          })\n          .refine((v) => v.minHeadingLevel <= v.maxHeadingLevel, {\n            message: \"minHeadingLevel must be <= maxHeadingLevel\",\n          }),\n      ])\n      .optional(),\n    lastUpdated: z.coerce\n      .date({ error: '\"lastUpdated\" must be a valid date (e.g. 2024-01-15)' })\n      .optional(),\n    /**\n     * Explicit per-page social/OG image override (path or absolute URL).\n     * When omitted, the page route is expected to fall back to a\n     * programmatically-generated card or the site-wide `config.socialImage`.\n     */\n    socialImage: z\n      .string({ error: '\"socialImage\" must be a string (path or URL)' })\n      .optional(),\n    prev: prevNextSchema,\n    next: prevNextSchema,\n    /**\n     * Versioning rename escape hatch.\n     *\n     * When a page is renamed between versions (the URL slug changes), the\n     * newer version's frontmatter declares the slug it had in an older\n     * version. The framework uses this to link the pages as cross-version\n     * alternates and to emit a `<link rel=\"canonical\">` to the current\n     * version's URL.\n     *\n     * Example: `docs-v1/old-name.mdx` was renamed in v2 to `new-name.mdx`.\n     * On the new page (`docs/new-name.mdx`, current version), set:\n     *\n     *   previousSlug: old-name\n     *\n     * Now `/new-name` and `/v1/old-name` are linked as the same logical\n     * page in `<head>` alternates, and the v1 page's canonical points to\n     * `/new-name`.\n     *\n     * Accepts a single slug string (the page's id in the older version)\n     * or an array of strings when the page has been renamed across more\n     * than one version.\n     */\n    previousSlug: z\n      .union([z.string(), z.array(z.string())], {\n        error: '\"previousSlug\" must be a string or array of strings',\n      })\n      .optional(),\n  });\n}\n\n// ---------------------------------------------------------------------------\n// Public API\n// ---------------------------------------------------------------------------\n\n/**\n * Build a customizable docs schema. Use this when composing schemas outside\n * the `docsCollection()` factory (e.g. multiple docs collections with\n * different shapes).\n *\n * For typed Astro `image()` fields or per-collection field narrowing, use\n * the richer `defineSchema(ctx => ...)` factory instead.\n */\nexport function defineDocSchema(config: DocSchemaConfig = {}) {\n  const base = baseDocSchema();\n  // Apply the unknown-key check AFTER extends so user-added fields are\n  // recognized as valid. Order matters — `.passthrough().superRefine()`\n  // returns a ZodEffects, which can't be further `.extend()`-ed.\n  const merged = config.fields ? base.extend(config.fields) : base;\n  return withFrontmatterKeyCheck(merged);\n}\n\n/**\n * Factory options for `defineSchema`.\n *\n *   - `extend`: additional fields merged into the framework schema. Use\n *     this for user-defined frontmatter (`author`, `tags`, `cover`).\n *   - `narrow`: replaces framework fields with tighter types within this\n *     collection. Use when a collection has stricter rules — e.g.\n *     `{ mode: z.literal(\"doc\") }` says no landing pages in this collection.\n */\nexport interface DefineSchemaOptions {\n  extend?: z.ZodTypeAny;\n  narrow?: Record<string, z.ZodTypeAny>;\n}\n\n/**\n * Build a typed docs schema with access to the Astro `SchemaContext`.\n * Use this when you want typed image fields (`ctx.image()`), per-\n * collection narrowing of framework fields, or both. The simpler\n * `defineDocSchema({ fields })` factory is still available for the\n * common case of just adding fields.\n *\n *   import { defineCollection } from \"astro:content\";\n *   import { z } from \"astro/zod\";\n *   import { defineSchema } from \"nimbus-docs/schemas\";\n *\n *   export const collections = {\n *     docs: defineCollection({\n *       loader: ...,\n *       schema: defineSchema((ctx) => ({\n *         extend: z.object({\n *           cover: ctx.image().optional(),\n *           author: z.string().optional(),\n *         }),\n *         narrow: {\n *           mode: z.literal(\"doc\"),  // no landing pages here\n *         },\n *       })),\n *     }),\n *   };\n */\nexport function defineSchema(\n  factory: (ctx: import(\"astro:content\").SchemaContext) => DefineSchemaOptions,\n) {\n  return (ctx: import(\"astro:content\").SchemaContext) => {\n    const { extend, narrow } = factory(ctx);\n    let schema = baseDocSchema() as z.ZodObject<any>;\n\n    // narrowing first (overrides framework fields)\n    if (narrow) {\n      schema = schema.extend(narrow);\n    }\n\n    // additive extension (new user fields). Prefer .merge for ZodObject\n    // (preserves object-ness for downstream .extend); fall back to .and\n    // for any other Zod type (intersection, union, etc.).\n    if (extend) {\n      if (extend instanceof z.ZodObject) {\n        schema = schema.merge(extend);\n      } else {\n        // Intersection path — `.and()` returns ZodIntersection, on which\n        // we can't run `withUnknownKeyCheck` (it operates on ZodObject's\n        // `.shape`). Users on this path lose the removed-key migration\n        // diagnostic; they own that trade-off by reaching for the\n        // non-object extend.\n        return schema.and(extend);\n      }\n    }\n\n    return withFrontmatterKeyCheck(schema);\n  };\n}\n\n/** Default docs schema. Equivalent to `defineDocSchema()`. */\nexport const docsSchema = defineDocSchema();\n\nconst partialsObjectSchema = z.object({\n  /**\n   * Declared parameters this partial accepts.\n   * Suffix with `?` for optional params: `[\"name\", \"deprecated?\"]`\n   */\n  params: z.array(z.string()).optional(),\n});\n\n/** Schema for partials (`<Render file=\"...\" />` snippets). */\nexport const partialsSchema = partialsObjectSchema.default({});\n\n// ---------------------------------------------------------------------------\n// Lenient variants — used by `nimbus-docs lint` (`nimbus/frontmatter-shape`).\n//\n// The standalone lint CLI can't yet see a site's extended\n// `content.config.ts` schema, so it validates the *types* of the fields\n// the framework owns while tolerating user-added fields (passthrough).\n// Unknown-key detection is deferred to when the engine can load the real\n// per-collection schema.\n// ---------------------------------------------------------------------------\n\n/** Docs frontmatter, framework fields type-checked, extra keys allowed. */\nexport const lenientDocsSchema = baseDocSchema().passthrough();\n\n/** Partials frontmatter, framework fields type-checked, extra keys allowed. */\nexport const lenientPartialsSchema = partialsObjectSchema.passthrough();\n\n// ---------------------------------------------------------------------------\n// Components collection — used by sites documenting their own UI components.\n// Pair with `componentsCollection()` from `nimbus-docs/content`. Authoring\n// pattern: hero `<Showcase>` block + `<Example>` blocks in the MDX body, with\n// `props` declared in frontmatter for a generated prop table.\n// ---------------------------------------------------------------------------\n\n/** One row in a component's `props` frontmatter array. */\nconst componentPropSchema = z.object({\n  name: z.string({ error: 'prop needs a \"name\"' }),\n  type: z.string({ error: 'prop needs a \"type\"' }),\n  defaultValue: z.string().optional(),\n  required: z.boolean().default(false),\n  description: z.string({ error: 'prop needs a \"description\"' }),\n});\n\nexport type ComponentProp = z.infer<typeof componentPropSchema>;\n\n/** Default schema for the components collection. */\nexport const componentsSchema = z.object({\n  title: z.string({\n    error: (iss) =>\n      iss.input === undefined\n        ? 'Missing \"title\" in frontmatter — display name used in the sidebar and page header.'\n        : `\"title\" must be a string, received ${typeof iss.input}`,\n  }),\n  tagline: z.string({\n    error: (iss) =>\n      iss.input === undefined\n        ? 'Missing \"tagline\" in frontmatter — one-sentence summary shown under the title.'\n        : `\"tagline\" must be a string, received ${typeof iss.input}`,\n  }),\n  props: z.array(componentPropSchema).default([]),\n});\n"],"mappings":"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"}
+{"version":3,"file":"schemas.js","names":[],"sources":["../src/schemas.ts"],"sourcesContent":["/**\n * Content schemas for Nimbus.\n *\n * `docsSchema` is the default frontmatter contract for the `docs` collection.\n * `partialsSchema` is the contract for `<Render file=\"...\" />` partials.\n * `defineDocSchema(config)` returns a customizable schema for advanced users\n *   composing schemas outside the `docsCollection()` factory.\n *\n * Error messages target content authors, not framework developers.\n * Astro 6 ships Zod v4 via `astro/zod`. The v4 API uses a single `error`\n * field on every schema constructor — NOT v3's `required_error` /\n * `invalid_type_error` / `errorMap`.\n */\n\nimport { z } from \"astro/zod\";\nimport { withStrictKeys } from \"./_internal/strict-keys.js\";\n\nexport interface DocSchemaConfig<\n  TFields extends Record<string, z.ZodTypeAny> = Record<string, never>,\n> {\n  /**\n   * Additional frontmatter fields merged into the default schema.\n   * Generic-typed so the call-site shape is preserved through to\n   * `entry.data.<field>` access in consumer code.\n   */\n  fields?: TFields;\n}\n\n// ---------------------------------------------------------------------------\n// Building blocks\n// ---------------------------------------------------------------------------\n\nconst sidebarBadgeSchema = z.union([\n  z.string(),\n  z.object({\n    text: z.string({ error: 'sidebar badge needs a \"text\" field' }),\n    variant: z\n      .enum(\n        [\"default\", \"info\", \"note\", \"success\", \"tip\", \"warning\", \"caution\", \"danger\"],\n        {\n          error:\n            '\"variant\" must be one of: default, info, note, success, tip, warning, caution, danger',\n        },\n      )\n      .default(\"default\"),\n  }),\n]);\n\nconst sidebarSchema = z.object({\n  order: z.number({ error: '\"sidebar.order\" must be a number' }).optional(),\n  label: z.string({ error: '\"sidebar.label\" must be a string' }).optional(),\n  badge: sidebarBadgeSchema.optional(),\n  hidden: z.boolean({ error: '\"sidebar.hidden\" must be true or false' }).optional(),\n  hideChildren: z\n    .boolean({ error: '\"sidebar.hideChildren\" must be true or false' })\n    .optional(),\n});\n\nconst prevNextSchema = z\n  .union([\n    z.string(),\n    z.object({ link: z.string().optional(), label: z.string().optional() }),\n    z.literal(false),\n  ])\n  .optional();\n\nconst headElementSchema = z.object({\n  tag: z.enum([\"meta\", \"link\", \"script\", \"style\"], {\n    error: 'head element \"tag\" must be \"meta\", \"link\", \"script\", or \"style\"',\n  }),\n  attrs: z.record(z.string(), z.string()).default({}),\n  content: z.string().optional(),\n});\n\n// Mirrors `BannerProps` in types.ts. Layouts consume this directly off\n// `entry.data.banner` and render the `<Banner>` component with it, so the\n// schema is framework-owned (not user-extensible territory).\nconst bannerSchema = z.object({\n  content: z.string({ error: 'banner \"content\" must be a string' }),\n  type: z\n    .enum([\"note\", \"tip\", \"caution\", \"danger\"], {\n      error: 'banner \"type\" must be one of: note, tip, caution, danger',\n    })\n    .optional(),\n  dismissible: z\n    .object({\n      id: z.string({\n        error: 'banner \"dismissible.id\" must be a string — a stable identifier you bump when banner content meaningfully changes',\n      }),\n      days: z.number({ error: 'banner \"dismissible.days\" must be a number' }).optional(),\n    })\n    .optional(),\n});\n\n// ---------------------------------------------------------------------------\n// Removed/renamed frontmatter keys — surface migration errors loudly\n// ---------------------------------------------------------------------------\n\n/**\n * Frontmatter keys that used to exist but no longer do. When user content\n * still carries one of these, Zod's default `.strip()` behavior would\n * silently drop it — the page would build, but with subtly different\n * behavior (the old toggle just disappears). That's a confusing failure\n * mode for an authoring contract.\n *\n * `withUnknownKeyCheck` (below) consults this map. Hits get the friendly\n * migration message verbatim; everything else falls through to a generic\n * \"Unknown frontmatter key\" error so typos don't sneak past either.\n *\n * Entries removed in the v0 → v1 cleanup:\n *\n *   - `template` → `mode`: same shape, but `\"splash\"` is now `\"custom\"`.\n *   - `pagefind` → `searchable`: same boolean; default now derives from\n *     `noindex` (a non-crawlable page is non-searchable by default).\n *   - `llms`: removed. All published pages are listed in `/llms.txt`; the\n *     escape hatch is `noindex: true`.\n *   - `aiDeprioritize`: removed. The framework no longer emits an\n *     agent-downrank signal.\n *   - `hero`: removed. Compose the hero in MDX body with user-owned\n *     components instead of a frontmatter contract.\n */\nconst REMOVED_FRONTMATTER_KEYS: Record<string, string> = {\n  template:\n    'was renamed to \"mode\". Replace `template: \"doc\"` with `mode: \"doc\"`, and `template: \"splash\"` with `mode: \"custom\"`.',\n  pagefind:\n    'was renamed to \"searchable\". Same boolean shape; the default now derives from `noindex` (a non-crawlable page is non-searchable unless you set `searchable: true` explicitly).',\n  llms:\n    \"was removed. Every published page is now listed in /llms.txt; use `noindex: true` to keep a page out of both search engines and the LLM index.\",\n  aiDeprioritize:\n    \"was removed. The framework no longer emits an agent-downrank signal. If you want a page hidden from agents, use `noindex: true`.\",\n  hero:\n    \"was removed. Compose your hero in the MDX body using user-owned components; there is no longer a `hero` frontmatter contract.\",\n};\n\n/**\n * Apply this AFTER any `.extend()` so user-added fields are recognized\n * as valid. Wraps the schema in `.passthrough().superRefine()` so removed\n * keys raise a guided migration error; other unknown keys raise a\n * generic error pointing at `defineSchema({ extend: ... })`.\n */\nfunction withFrontmatterKeyCheck<T extends z.ZodObject<z.ZodRawShape>>(schema: T) {\n  return withStrictKeys(schema, {\n    removedKeys: REMOVED_FRONTMATTER_KEYS,\n    contextLabel: \"Frontmatter key\",\n    unknownHint: (key) =>\n      `If you meant to add a custom field, declare it in your collection's schema via \\`defineSchema({ extend: z.object({ ${key}: ... }) })\\`.`,\n  });\n}\n\n// ---------------------------------------------------------------------------\n// Base docs schema\n// ---------------------------------------------------------------------------\n\nfunction baseDocSchema() {\n  return z.object({\n    title: z.string({\n      error: (iss) =>\n        iss.input === undefined\n          ? 'Missing required \"title\" in frontmatter. Every doc needs:\\n\\n  ---\\n  title: \"Your Page Title\"\\n  ---'\n          : `\"title\" must be a string, received ${typeof iss.input}`,\n    }),\n    description: z.string({ error: '\"description\" must be a string' }).optional(),\n    mode: z\n      .enum([\"doc\", \"custom\"], {\n        error: '\"mode\" must be \"doc\" or \"custom\"',\n      })\n      .default(\"doc\"),\n    sidebar: z.union([z.literal(false), sidebarSchema]).optional(),\n    head: z.array(headElementSchema).default([]),\n    banner: bannerSchema.optional(),\n    draft: z.boolean({ error: '\"draft\" must be true or false' }).default(false),\n    noindex: z.boolean({ error: '\"noindex\" must be true or false' }).default(false),\n    /**\n     * Whether this page is included in the site search index. When omitted,\n     * derives from `noindex` (a page that's not crawlable is by default not\n     * searchable). Set explicitly to override — e.g. `{ noindex: true,\n     * searchable: true }` keeps the page out of search engines but findable\n     * in the site's own search.\n     */\n    searchable: z\n      .boolean({ error: '\"searchable\" must be true or false' })\n      .optional(),\n    tableOfContents: z\n      .union([\n        z.literal(false),\n        z\n          .object({\n            minHeadingLevel: z\n              .number({ error: '\"minHeadingLevel\" must be a number (1-6)' })\n              .int()\n              .min(1)\n              .max(6)\n              .default(2),\n            maxHeadingLevel: z\n              .number({ error: '\"maxHeadingLevel\" must be a number (1-6)' })\n              .int()\n              .min(1)\n              .max(6)\n              .default(3),\n          })\n          .refine((v) => v.minHeadingLevel <= v.maxHeadingLevel, {\n            message: \"minHeadingLevel must be <= maxHeadingLevel\",\n          }),\n      ])\n      .optional(),\n    lastUpdated: z.coerce\n      .date({ error: '\"lastUpdated\" must be a valid date (e.g. 2024-01-15)' })\n      .optional(),\n    /**\n     * Explicit per-page social/OG image override (path or absolute URL).\n     * When omitted, the page route is expected to fall back to a\n     * programmatically-generated card or the site-wide `config.socialImage`.\n     */\n    socialImage: z\n      .string({ error: '\"socialImage\" must be a string (path or URL)' })\n      .optional(),\n    prev: prevNextSchema,\n    next: prevNextSchema,\n    /**\n     * Versioning rename escape hatch.\n     *\n     * When a page is renamed between versions (the URL slug changes), the\n     * newer version's frontmatter declares the slug it had in an older\n     * version. The framework uses this to link the pages as cross-version\n     * alternates and to emit a `<link rel=\"canonical\">` to the current\n     * version's URL.\n     *\n     * Example: `docs-v1/old-name.mdx` was renamed in v2 to `new-name.mdx`.\n     * On the new page (`docs/new-name.mdx`, current version), set:\n     *\n     *   previousSlug: old-name\n     *\n     * Now `/new-name` and `/v1/old-name` are linked as the same logical\n     * page in `<head>` alternates, and the v1 page's canonical points to\n     * `/new-name`.\n     *\n     * Accepts a single slug string (the page's id in the older version)\n     * or an array of strings when the page has been renamed across more\n     * than one version.\n     */\n    previousSlug: z\n      .union([z.string(), z.array(z.string())], {\n        error: '\"previousSlug\" must be a string or array of strings',\n      })\n      .optional(),\n  });\n}\n\n// ---------------------------------------------------------------------------\n// Public API\n// ---------------------------------------------------------------------------\n\n/**\n * Build a customizable docs schema. Use this when composing schemas outside\n * the `docsCollection()` factory (e.g. multiple docs collections with\n * different shapes).\n *\n * For typed Astro `image()` fields or per-collection field narrowing, use\n * the richer `defineSchema(ctx => ...)` factory instead.\n */\nexport function defineDocSchema<\n  TFields extends Record<string, z.ZodTypeAny> = Record<string, never>,\n>(config: DocSchemaConfig<TFields> = {}) {\n  const base = baseDocSchema();\n  // Always extend (with `{}` when no fields) so the result type is\n  // `ZodObject<baseShape & TFields>` rather than a union of branches.\n  // A union widens the consumer view of `entry.data.X` to the intersection\n  // of branch fields, which is \"no fields\" for the false branch and\n  // re-erases everything we just preserved.\n  const merged = base.extend((config.fields ?? {}) as TFields);\n  // Cast back to the underlying ZodObject. Runtime wrap (`.passthrough()\n  // .superRefine()`) stays — the unknown-key check still fires. But tsdown\n  // collapses ZodEffects emissions to `ZodObject<Record<string, ZodType<unknown>>>`,\n  // erasing every framework field type at every consumer's `entry.data.X`\n  // access. The cast preserves the field shapes through .d.ts emission.\n  return withFrontmatterKeyCheck(merged) as unknown as typeof merged;\n}\n\n/**\n * Factory options for `defineSchema`.\n *\n *   - `extend`: additional fields merged into the framework schema. Use\n *     this for user-defined frontmatter (`author`, `tags`, `cover`).\n *   - `narrow`: replaces framework fields with tighter types within this\n *     collection. Use when a collection has stricter rules — e.g.\n *     `{ mode: z.literal(\"doc\") }` says no landing pages in this collection.\n */\nexport interface DefineSchemaOptions {\n  extend?: z.ZodTypeAny;\n  narrow?: Record<string, z.ZodTypeAny>;\n}\n\n/**\n * Build a typed docs schema with access to the Astro `SchemaContext`.\n * Use this when you want typed image fields (`ctx.image()`), per-\n * collection narrowing of framework fields, or both. The simpler\n * `defineDocSchema({ fields })` factory is still available for the\n * common case of just adding fields.\n *\n *   import { defineCollection } from \"astro:content\";\n *   import { z } from \"astro/zod\";\n *   import { defineSchema } from \"nimbus-docs/schemas\";\n *\n *   export const collections = {\n *     docs: defineCollection({\n *       loader: ...,\n *       schema: defineSchema((ctx) => ({\n *         extend: z.object({\n *           cover: ctx.image().optional(),\n *           author: z.string().optional(),\n *         }),\n *         narrow: {\n *           mode: z.literal(\"doc\"),  // no landing pages here\n *         },\n *       })),\n *     }),\n *   };\n */\nexport function defineSchema(\n  factory: (ctx: import(\"astro:content\").SchemaContext) => DefineSchemaOptions,\n) {\n  return (ctx: import(\"astro:content\").SchemaContext) => {\n    const { extend, narrow } = factory(ctx);\n    let schema = baseDocSchema() as z.ZodObject<any>;\n\n    // narrowing first (overrides framework fields)\n    if (narrow) {\n      schema = schema.extend(narrow);\n    }\n\n    // additive extension (new user fields). Prefer .merge for ZodObject\n    // (preserves object-ness for downstream .extend); fall back to .and\n    // for any other Zod type (intersection, union, etc.).\n    if (extend) {\n      if (extend instanceof z.ZodObject) {\n        schema = schema.merge(extend);\n      } else {\n        // Intersection path — `.and()` returns ZodIntersection, on which\n        // we can't run `withUnknownKeyCheck` (it operates on ZodObject's\n        // `.shape`). Users on this path lose the removed-key migration\n        // diagnostic; they own that trade-off by reaching for the\n        // non-object extend.\n        return schema.and(extend);\n      }\n    }\n\n    return withFrontmatterKeyCheck(schema);\n  };\n}\n\n/** Default docs schema. Equivalent to `defineDocSchema()`. */\nexport const docsSchema = defineDocSchema();\n\nconst partialsObjectSchema = z.object({\n  /**\n   * Declared parameters this partial accepts.\n   * Suffix with `?` for optional params: `[\"name\", \"deprecated?\"]`\n   */\n  params: z.array(z.string()).optional(),\n});\n\n/** Schema for partials (`<Render file=\"...\" />` snippets). */\nexport const partialsSchema = partialsObjectSchema.default({});\n\n// ---------------------------------------------------------------------------\n// Lenient variants — used by `nimbus-docs lint` (`nimbus/frontmatter-shape`).\n//\n// The standalone lint CLI can't yet see a site's extended\n// `content.config.ts` schema, so it validates the *types* of the fields\n// the framework owns while tolerating user-added fields (passthrough).\n// Unknown-key detection is deferred to when the engine can load the real\n// per-collection schema.\n// ---------------------------------------------------------------------------\n\n/** Docs frontmatter, framework fields type-checked, extra keys allowed. */\nexport const lenientDocsSchema = baseDocSchema().passthrough();\n\n/** Partials frontmatter, framework fields type-checked, extra keys allowed. */\nexport const lenientPartialsSchema = partialsObjectSchema.passthrough();\n\n// ---------------------------------------------------------------------------\n// Components collection — used by sites documenting their own UI components.\n// Pair with `componentsCollection()` from `nimbus-docs/content`. Authoring\n// pattern: hero `<Showcase>` block + `<Example>` blocks in the MDX body, with\n// `props` declared in frontmatter for a generated prop table.\n// ---------------------------------------------------------------------------\n\n/** One row in a component's `props` frontmatter array. */\nconst componentPropSchema = z.object({\n  name: z.string({ error: 'prop needs a \"name\"' }),\n  type: z.string({ error: 'prop needs a \"type\"' }),\n  defaultValue: z.string().optional(),\n  required: z.boolean().default(false),\n  description: z.string({ error: 'prop needs a \"description\"' }),\n});\n\nexport type ComponentProp = z.infer<typeof componentPropSchema>;\n\n/** Default schema for the components collection. */\nexport const componentsSchema = z.object({\n  title: z.string({\n    error: (iss) =>\n      iss.input === undefined\n        ? 'Missing \"title\" in frontmatter — display name used in the sidebar and page header.'\n        : `\"title\" must be a string, received ${typeof iss.input}`,\n  }),\n  tagline: z.string({\n    error: (iss) =>\n      iss.input === undefined\n        ? 'Missing \"tagline\" in frontmatter — one-sentence summary shown under the title.'\n        : `\"tagline\" must be a string, received ${typeof iss.input}`,\n  }),\n  props: z.array(componentPropSchema).default([]),\n});\n"],"mappings":"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"}

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-import { a as SeverityConfig, i as Severity, n as DiagnosticFix, r as RuleCode, t as Diagnostic } from "./diagnostic-DZf0z79l.js";
+import { a as Severity, i as RuleCode, n as Diagnostic, o as SeverityConfig, r as DiagnosticFix, t as AuthoringRuleCode } from "./diagnostic-C6OaBe_o.js";
 
 //#region src/types.d.ts
 /**
@@ -438,5 +438,5 @@ interface DocsPageProps extends BasePageProps {
   prevNext: PrevNext;
 }
 //#endregion
-export { BadgeVariant, BannerProps, BasePageProps, Breadcrumb, type Diagnostic, type DiagnosticFix, DocsPageProps, FeaturesConfig, HeadElement, NimbusConfig, PrevNext, PrevNextLink, PrevNextOverrides, ResolvedVersions, type RuleCode, SearchConfig, SearchProvider, SearchResult, type Severity, type SeverityConfig, SidebarBadge, SidebarConfig, SidebarConfigItem, SidebarExternalLinkItem, SidebarGroupItem, SidebarItem, SidebarLinkItem, SidebarSection, TOCItem, VersionAlternateRecord, VersionAlternatesTable, VersionPageRef, VersionStatus, VersionsConfig };
+export { type AuthoringRuleCode, BadgeVariant, BannerProps, BasePageProps, Breadcrumb, type Diagnostic, type DiagnosticFix, DocsPageProps, FeaturesConfig, HeadElement, NimbusConfig, PrevNext, PrevNextLink, PrevNextOverrides, ResolvedVersions, type RuleCode, SearchConfig, SearchProvider, SearchResult, type Severity, type SeverityConfig, SidebarBadge, SidebarConfig, SidebarConfigItem, SidebarExternalLinkItem, SidebarGroupItem, SidebarItem, SidebarLinkItem, SidebarSection, TOCItem, VersionAlternateRecord, VersionAlternatesTable, VersionPageRef, VersionStatus, VersionsConfig };
 //# sourceMappingURL=types.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nimbus-docs",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "private": false,
   "type": "module",
   "description": "Docs, for humans and agents",
@@ -46,6 +46,10 @@
       "types": "./dist/client.d.ts",
       "import": "./dist/client.js"
     },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js"
+    },
     "./lib/pkgm": {
       "types": "./dist/lib/pkgm.d.ts",
       "import": "./dist/lib/pkgm.js"
@@ -54,10 +58,21 @@
   },
   "files": [
     "dist",
-    "src/components"
+    "src/components",
+    "CHANGELOG.md"
   ],
   "peerDependencies": {
-    "astro": ">=6.4.0"
+    "astro": ">=6.4.0",
+    "react": ">=19.0.0",
+    "react-dom": ">=19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
   },
   "dependencies": {
     "@astrojs/markdown-satteri": "^0.2.1",
@@ -66,14 +81,10 @@
     "@clack/prompts": "^0.9.1",
     "@shikijs/transformers": "^4.1.0",
     "@vercel/detect-agent": "^1.2.3",
-    "mri": "^1.2.0",
-    "satteri": "^0.6.3",
-    "yaml": "^2.7.1"
-  },
-  "devDependencies": {
-    "@shikijs/types": "^4.1.0",
-    "astro": "^6.4.0",
+    "clsx": "^2.1.1",
     "github-slugger": "^2.0.0",
+    "mri": "^1.2.0",
+    "tailwind-merge": "^3.5.0",
     "remark-lint-emphasis-marker": "^4.0.1",
     "remark-lint-fenced-code-flag": "^4.2.0",
     "remark-lint-heading-increment": "^4.0.1",
@@ -82,11 +93,17 @@
     "remark-lint-no-literal-urls": "^4.0.1",
     "remark-lint-no-multiple-toplevel-headings": "^4.0.1",
     "remark-lint-unordered-list-marker-style": "^4.0.1",
+    "satteri": "^0.6.3",
+    "unified": "^11.0.5",
+    "vfile": "^6.0.3",
+    "yaml": "^2.7.1"
+  },
+  "devDependencies": {
+    "@shikijs/types": "^4.1.0",
+    "astro": "^6.4.0",
     "tsdown": "^0.20.3",
     "tsx": "^4.22.3",
-    "typescript": "^5.8.3",
-    "unified": "^11.0.5",
-    "vfile": "^6.0.3"
+    "typescript": "^5.8.3"
   },
   "scripts": {
     "build": "tsdown",

package/dist/diagnostic-DZf0z79l.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"diagnostic-DZf0z79l.d.ts","names":[],"sources":["../src/lint/diagnostic.ts"],"mappings":";;AAyBA;;;;;;;;;;;;;;;;;;;;;;;cAAa,UAAA;EAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KA0BD,QAAA,gBAAwB,UAAA;;;KAIxB,QAAA;;KAGA,cAAA,GAAiB,QAAA;AAAA,UAEZ,aAAA;EAyBT;EAvBN,WAAA;EAuBmB;;;;EAlBnB,KAAA,EAAO,KAAA;IAAQ,KAAA;IAAyB,IAAA;EAAA;AAAA;AAAA,UAGzB,UAAA;EACf,IAAA,EAAM,QAAA;EACN,QAAA,EAAU,QAAA;;;EAGV,MAAA;EACA,OAAA;;EAEA,IAAA;;EAEA,IAAA;;EAEA,MAAA;EACA,OAAA;EACA,SAAA;EACA,GAAA,GAAM,aAAA;AAAA"}