npm - @waveso/docs - Versions diffs - 0.1.0 → 0.3.0 - Mend

@waveso/docs 0.1.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (79) hide show

package/CHANGELOG.md +194 -0
package/README.md +592 -88
package/dist/code-frame.d.ts +29 -0
package/dist/code-frame.js +41 -0
package/dist/code-meta.d.ts +48 -0
package/dist/code-meta.js +72 -0
package/dist/docs-content-id.d.ts +19 -0
package/dist/docs-content-id.js +19 -0
package/dist/docs-error.d.ts +19 -0
package/dist/docs-error.js +28 -0
package/dist/errors.d.ts +94 -0
package/dist/errors.js +45 -0
package/dist/frontmatter.d.ts +39 -7
package/dist/frontmatter.js +51 -24
package/dist/highlighter.d.ts +2 -2
package/dist/highlighter.js +3 -2
package/dist/map-pooled.d.ts +26 -0
package/dist/map-pooled.js +45 -0
package/dist/meta.d.ts +7 -3
package/dist/meta.js +61 -15
package/dist/next.d.ts +182 -35
package/dist/next.js +177 -49
package/dist/plugins/rehype-capture-toc.js +52 -20
package/dist/plugins/rehype-code-frame.d.ts +10 -0
package/dist/plugins/rehype-code-frame.js +88 -0
package/dist/plugins/rehype-code-language.d.ts +24 -0
package/dist/plugins/rehype-code-language.js +54 -0
package/dist/plugins/rehype-fallback-heading-ids.d.ts +6 -0
package/dist/plugins/rehype-fallback-heading-ids.js +51 -0
package/dist/plugins/rehype-flatten-roots.d.ts +7 -0
package/dist/plugins/rehype-flatten-roots.js +39 -0
package/dist/plugins/remark-doc-links.d.ts +12 -1
package/dist/plugins/remark-doc-links.js +147 -20
package/dist/react/code-runtime.d.ts +14 -0
package/dist/react/code-runtime.js +161 -0
package/dist/react/doc-content.d.ts +39 -2
package/dist/react/doc-content.js +42 -10
package/dist/react/layout.d.ts +44 -0
package/dist/react/layout.js +65 -0
package/dist/react/markdown-components.js +71 -6
package/dist/react/nav.d.ts +28 -0
package/dist/react/nav.js +70 -0
package/dist/react/nearest-scroll-top.d.ts +45 -0
package/dist/react/nearest-scroll-top.js +44 -0
package/dist/react/next-link.d.ts +34 -0
package/dist/react/next-link.js +30 -0
package/dist/react/next-nav.d.ts +11 -0
package/dist/react/next-nav.js +32 -0
package/dist/react/next-search.d.ts +22 -0
package/dist/react/next-search.js +52 -0
package/dist/react/search-dialog.d.ts +35 -7
package/dist/react/search-dialog.js +55 -33
package/dist/react/shell-labels.d.ts +43 -0
package/dist/react/shell-labels.js +27 -0
package/dist/react/sidebar.d.ts +38 -3
package/dist/react/sidebar.js +104 -12
package/dist/react/skip-link.d.ts +1 -9
package/dist/react/skip-link.js +6 -5
package/dist/react/toc.d.ts +12 -4
package/dist/react/toc.js +46 -12
package/dist/react/youtube.d.ts +31 -5
package/dist/react/youtube.js +76 -52
package/dist/render.d.ts +78 -10
package/dist/render.js +137 -54
package/dist/route-path.d.ts +46 -0
package/dist/route-path.js +51 -0
package/dist/search-index.d.ts +22 -21
package/dist/search-index.js +27 -78
package/dist/search-options.d.ts +32 -1
package/dist/search-options.js +66 -3
package/dist/section-boundary.d.ts +17 -0
package/dist/section-boundary.js +43 -0
package/dist/sitemap-limit.d.ts +34 -0
package/dist/sitemap-limit.js +37 -0
package/dist/source.d.ts +12 -22
package/dist/source.js +165 -72
package/dist/styles.css +1117 -125
package/dist/types.d.ts +52 -29
package/package.json +70 -34

package/dist/code-frame.d.ts ADDED Viewed

@@ -0,0 +1,29 @@
+import { Root } from "hast";
+//#region src/code-frame.d.ts
+/** Marks the `<figure>` a code block is wrapped in. */
+declare const CODE_FRAME_ATTRIBUTE = "data-wave-docs-code";
+/** The copy button inside that figure. */
+declare const CODE_COPY_ATTRIBUTE = "data-wave-docs-copy";
+/**
+ * Set on `<html>` by the runtime once its listener is attached.
+ *
+ * ⚠️ THIS IS WHAT CLOSES THE INERT-MARKUP TRAP, AND IT IS STRUCTURAL RATHER
+ * THAN DOCUMENTED. The button is in the HTML whether or not any JavaScript
+ * runs — a `renderToStaticMarkup` consumer, a reader with scripts off, anyone
+ * rendering the hast by hand. The stylesheet keeps it `visibility: hidden`
+ * until this attribute appears, which also takes it out of the tab order, so
+ * none of those readers meets a button that silently does nothing or a dead
+ * tab stop where a control should be.
+ */
+declare const CODE_READY_ATTRIBUTE = "data-wave-docs-code-ready";
+/**
+ * Whether a tree contains a code frame.
+ *
+ * `DocContent` asks before rendering the runtime, so a page with no fences
+ * ships zero extra bytes rather than a client component that finds nothing to
+ * do. The server has the tree in hand and this is one pass over it, so the
+ * check costs nothing the render was not already paying.
+ */
+declare function hasCodeFrame(tree: Root): boolean;
+//#endregion
+export { CODE_COPY_ATTRIBUTE, CODE_FRAME_ATTRIBUTE, CODE_READY_ATTRIBUTE, hasCodeFrame };

package/dist/code-frame.js ADDED Viewed

@@ -0,0 +1,41 @@
+//#region src/code-frame.ts
+/** Marks the `<figure>` a code block is wrapped in. */
+const CODE_FRAME_ATTRIBUTE = "data-wave-docs-code";
+/** The copy button inside that figure. */
+const CODE_COPY_ATTRIBUTE = "data-wave-docs-copy";
+/**
+* Set on `<html>` by the runtime once its listener is attached.
+*
+* ⚠️ THIS IS WHAT CLOSES THE INERT-MARKUP TRAP, AND IT IS STRUCTURAL RATHER
+* THAN DOCUMENTED. The button is in the HTML whether or not any JavaScript
+* runs — a `renderToStaticMarkup` consumer, a reader with scripts off, anyone
+* rendering the hast by hand. The stylesheet keeps it `visibility: hidden`
+* until this attribute appears, which also takes it out of the tab order, so
+* none of those readers meets a button that silently does nothing or a dead
+* tab stop where a control should be.
+*/
+const CODE_READY_ATTRIBUTE = "data-wave-docs-code-ready";
+/**
+* Whether a tree contains a code frame.
+*
+* `DocContent` asks before rendering the runtime, so a page with no fences
+* ships zero extra bytes rather than a client component that finds nothing to
+* do. The server has the tree in hand and this is one pass over it, so the
+* check costs nothing the render was not already paying.
+*/
+function hasCodeFrame(tree) {
+	return containsFrame(tree.children);
+}
+function containsFrame(nodes) {
+	for (const node of nodes) {
+		if (node.type !== "element") continue;
+		if (isCodeFrame(node)) return true;
+		if (containsFrame(node.children)) return true;
+	}
+	return false;
+}
+function isCodeFrame(node) {
+	return node.properties[CODE_FRAME_ATTRIBUTE] !== void 0;
+}
+//#endregion
+export { CODE_COPY_ATTRIBUTE, CODE_FRAME_ATTRIBUTE, CODE_READY_ATTRIBUTE, hasCodeFrame };

package/dist/code-meta.d.ts ADDED Viewed

@@ -0,0 +1,48 @@
+//#region src/code-meta.d.ts
+/**
+ * The bit after the language on a fence: ```` ```ts title="app/page.tsx" ````.
+ *
+ * Private — deliberately not an entry point. What a consumer sees is the
+ * `<figcaption>` it produces; the grammar is ours to extend.
+ *
+ * ## Read, never mutate
+ *
+ * `parseCodeMeta` takes a string and returns a value. It does not rewrite
+ * `code.data.meta`, and that restraint is the whole design: Shiki forwards the
+ * raw meta string to its transformers as `meta.__raw`, which is how
+ * `{1,3-5}` line highlighting and `showLineNumbers` will work when those land.
+ * A parser that consumed what it recognised would silently disable every
+ * feature it had not been taught about yet.
+ *
+ * ## Why `title=`
+ *
+ * Not a design question — a survey. Fumadocs, Starlight (via Expressive Code)
+ * and Docusaurus all spell it `title="…"`. Nextra's `filename=` and VitePress's
+ * `[filename]` are the minority, and `[…]` has nowhere to grow, so adopting it
+ * would mean two grammars in one meta string. `title` collides with frontmatter
+ * `title` as a word, which one comment fixes; making three of the five nearest
+ * comparators' users learn a second spelling does not have a fix.
+ *
+ * ## Unknown keys are ignored, malformed ones are not
+ *
+ * Shiki's meta string is an open namespace shared with its own transformers, so
+ * an author pasting `twoslash` or `{1,3}` from another site's documentation must
+ * not fail the build. But `title=app/page.tsx` — unquoted — is a *malformed*
+ * `title`, and ignoring it silently ships a caption reading `app/page.tsx` only
+ * up to the first space, or no caption at all. That throws, naming the file.
+ */
+/** What a fence's meta string asked for. */
+interface CodeMeta {
+  /** The `<figcaption>` text, and part of the copy button's accessible name. */
+  title?: string | undefined;
+}
+/**
+ * Read {@link CodeMeta} out of a fence's meta string.
+ *
+ * `path` is only ever used to name the offending document in an error. The
+ * alternative — an error saying `title=` was malformed, on a site with four
+ * hundred pages — is a grep.
+ */
+declare function parseCodeMeta(meta: string | undefined, path: string): CodeMeta;
+//#endregion
+export { CodeMeta, parseCodeMeta };

package/dist/code-meta.js ADDED Viewed

@@ -0,0 +1,72 @@
+import { docsError } from "./docs-error.js";
+//#region src/code-meta.ts
+/**
+* The bit after the language on a fence: ```` ```ts title="app/page.tsx" ````.
+*
+* Private — deliberately not an entry point. What a consumer sees is the
+* `<figcaption>` it produces; the grammar is ours to extend.
+*
+* ## Read, never mutate
+*
+* `parseCodeMeta` takes a string and returns a value. It does not rewrite
+* `code.data.meta`, and that restraint is the whole design: Shiki forwards the
+* raw meta string to its transformers as `meta.__raw`, which is how
+* `{1,3-5}` line highlighting and `showLineNumbers` will work when those land.
+* A parser that consumed what it recognised would silently disable every
+* feature it had not been taught about yet.
+*
+* ## Why `title=`
+*
+* Not a design question — a survey. Fumadocs, Starlight (via Expressive Code)
+* and Docusaurus all spell it `title="…"`. Nextra's `filename=` and VitePress's
+* `[filename]` are the minority, and `[…]` has nowhere to grow, so adopting it
+* would mean two grammars in one meta string. `title` collides with frontmatter
+* `title` as a word, which one comment fixes; making three of the five nearest
+* comparators' users learn a second spelling does not have a fix.
+*
+* ## Unknown keys are ignored, malformed ones are not
+*
+* Shiki's meta string is an open namespace shared with its own transformers, so
+* an author pasting `twoslash` or `{1,3}` from another site's documentation must
+* not fail the build. But `title=app/page.tsx` — unquoted — is a *malformed*
+* `title`, and ignoring it silently ships a caption reading `app/page.tsx` only
+* up to the first space, or no caption at all. That throws, naming the file.
+*/
+/**
+* `title="…"`, anywhere in the string, with the value in double quotes.
+*
+* A filename containing a double quote is inexpressible, and gets no escape
+* mechanism: no real path has one, and an escape grammar is a permanent tax on
+* every reader of this regex to serve a case that does not occur.
+*/
+const TITLE = /(^|\s)title="([^"]*)"/;
+/**
+* A `title=` at a word boundary, however it is spelled.
+*
+* Only consulted once {@link TITLE} has already failed, so reaching this means
+* the author wrote a title the one grammar cannot read — unquoted,
+* single-quoted, or opened and never closed. An earlier version excluded
+* anything followed by a quote, which let `title="a.ts` (no closing quote)
+* fall through and produce no caption at all, silently. That is the failure
+* this function exists to make loud.
+*/
+const MALFORMED_TITLE = /(^|\s)title=/;
+/**
+* Read {@link CodeMeta} out of a fence's meta string.
+*
+* `path` is only ever used to name the offending document in an error. The
+* alternative — an error saying `title=` was malformed, on a site with four
+* hundred pages — is a grep.
+*/
+function parseCodeMeta(meta, path) {
+	if (meta === void 0 || meta.trim() === "") return {};
+	const matched = TITLE.exec(meta);
+	if (matched === null) {
+		if (MALFORMED_TITLE.test(meta)) throw docsError("invalid-code-meta", `${path}: a code fence has a malformed \`title\`. Write it as \`title="app/page.tsx"\`, with double quotes — an unquoted title stops at the first space, and a title containing a double quote cannot be expressed. Got: \`${meta.trim()}\``);
+		return {};
+	}
+	const title = matched[2];
+	return title === void 0 || title === "" ? {} : { title };
+}
+//#endregion
+export { parseCodeMeta };

package/dist/docs-content-id.d.ts ADDED Viewed

@@ -0,0 +1,19 @@
+//#region src/docs-content-id.d.ts
+/**
+ * The id of the rendered `<article>`, and the target of the skip link.
+ *
+ * Private — deliberately not an entry point in `package.json`. The documented
+ * import is `@waveso/docs/react/skip-link`, which re-exports it; this module
+ * exists so `src/next.ts` can have the constant without importing a
+ * `'use client'` module for a string.
+ *
+ * One constant for both halves, and no way to change it. The two files spelled
+ * it independently once, and a skip link pointing at an id nothing carries
+ * scrolls nowhere and focuses nothing — a failure with no symptom until a
+ * keyboard user hits it. `createDocsRoute` used to accept a `contentId` option
+ * that broke exactly that pairing, silently, because `SkipLink` had no matching
+ * option to follow it with.
+ */
+declare const DOCS_CONTENT_ID = "docs-content";
+//#endregion
+export { DOCS_CONTENT_ID };

package/dist/docs-content-id.js ADDED Viewed

@@ -0,0 +1,19 @@
+//#region src/docs-content-id.ts
+/**
+* The id of the rendered `<article>`, and the target of the skip link.
+*
+* Private — deliberately not an entry point in `package.json`. The documented
+* import is `@waveso/docs/react/skip-link`, which re-exports it; this module
+* exists so `src/next.ts` can have the constant without importing a
+* `'use client'` module for a string.
+*
+* One constant for both halves, and no way to change it. The two files spelled
+* it independently once, and a skip link pointing at an id nothing carries
+* scrolls nowhere and focuses nothing — a failure with no symptom until a
+* keyboard user hits it. `createDocsRoute` used to accept a `contentId` option
+* that broke exactly that pairing, silently, because `SkipLink` had no matching
+* option to follow it with.
+*/
+const DOCS_CONTENT_ID = "docs-content";
+//#endregion
+export { DOCS_CONTENT_ID };

package/dist/docs-error.d.ts ADDED Viewed

@@ -0,0 +1,19 @@
+import { DocsError, DocsErrorCode } from "./errors.js";
+//#region src/docs-error.d.ts
+/**
+ * Build an error that names this package and says what class of thing failed.
+ *
+ * The message is passed through untouched apart from the prefix, which is added
+ * only when absent — the wording at each throw site is the part a human reads,
+ * and several of them took real effort to get right.
+ *
+ * `code` is attached non-enumerably so it does not appear in `JSON.stringify`
+ * or a spread, which keeps error objects looking exactly as they did while
+ * still being branchable.
+ *
+ * The stack is left alone. Flattening it would hide the `dist/` frames a
+ * consumer does not care about, and also the ones a maintainer needs.
+ */
+declare function docsError(code: DocsErrorCode, message: string, options?: ErrorOptions): DocsError;
+//#endregion
+export { docsError };

package/dist/docs-error.js ADDED Viewed

@@ -0,0 +1,28 @@
+import { DOCS_ERROR_PREFIX } from "./errors.js";
+//#region src/docs-error.ts
+/**
+* Build an error that names this package and says what class of thing failed.
+*
+* The message is passed through untouched apart from the prefix, which is added
+* only when absent — the wording at each throw site is the part a human reads,
+* and several of them took real effort to get right.
+*
+* `code` is attached non-enumerably so it does not appear in `JSON.stringify`
+* or a spread, which keeps error objects looking exactly as they did while
+* still being branchable.
+*
+* The stack is left alone. Flattening it would hide the `dist/` frames a
+* consumer does not care about, and also the ones a maintainer needs.
+*/
+function docsError(code, message, options) {
+	const error = new Error(message.startsWith("@waveso/docs: ") ? message : `${DOCS_ERROR_PREFIX}${message}`, options);
+	Object.defineProperty(error, "code", {
+		value: code,
+		enumerable: false,
+		writable: false,
+		configurable: true
+	});
+	return error;
+}
+//#endregion
+export { docsError };

package/dist/errors.d.ts ADDED Viewed

@@ -0,0 +1,94 @@
+//#region src/errors.d.ts
+/**
+ * The error taxonomy, as public API.
+ *
+ * Every failure this package raises is an `Error` whose message names the
+ * package and which carries a `code` off this union. That exists so a host can
+ * branch — downgrade broken-link failures in a preview build, say, or report
+ * `invalid-frontmatter` differently from `missing-peer` — and until this
+ * module was an entry point there was no supported way to do it. The taxonomy
+ * said "branch on this" while the module said "you cannot import me", and the
+ * two paragraphs contradicted each other for nineteen codes and forty-five
+ * call sites.
+ *
+ * ```ts
+ * import { isDocsError } from '@waveso/docs/errors';
+ *
+ * try {
+ *   await docs.renderAll();
+ * } catch (error) {
+ *   if (isDocsError(error) && error.code === 'draft-link') {
+ *     console.warn(error.message);
+ *   } else {
+ *     throw error;
+ *   }
+ * }
+ * ```
+ *
+ * No class is exported, and that is deliberate: `instanceof` against a copy of
+ * this module resolved twice — a monorepo with two versions installed, a
+ * bundler that duplicates it — silently answers `false`. A string `code` and a
+ * structural guard have no such failure mode.
+ */
+/** Prefix every message carries, so a stack trace names the culprit package. */
+declare const DOCS_ERROR_PREFIX = "@waveso/docs: ";
+/**
+ * What went wrong, as something a consumer can branch on.
+ *
+ * Before this existed, every failure was a bare `Error` and roughly half the
+ * messages omitted the package prefix, so a host wanting to downgrade (say)
+ * broken-link failures in dev had nothing to test but the message text — and
+ * `message.startsWith('@waveso/docs:')` was not even a reliable filter.
+ */
+type DocsErrorCode =
+/** A link resolves to a route no published page owns. */
+'broken-link' |
+/** A link resolves to a page that exists but is `draft: true`. */
+'draft-link' |
+/** A link resolves to an alias, which is a redirect and not a page. */
+'alias-link' |
+/** An `aliases` entry is empty, escapes the root, or is not URL-safe. */
+'invalid-alias' |
+/** Two pages claim one alias, or an alias shadows a real route. */
+'alias-collision' |
+/** Two files resolve to the same route. */
+'route-collision' |
+/** A page's frontmatter is missing, malformed, or rejected by the schema. */
+'invalid-frontmatter' |
+/** A `meta.json` is malformed, or names something that is not there. */
+'invalid-meta' |
+/** An option passed to this package cannot be used as given. */
+'invalid-config' |
+/** `contentDir` does not point at a readable directory. */
+'missing-content-dir' |
+/** A markdown page is reachable only through a broken symbolic link. */
+'broken-symlink' |
+/** An `imageResolver` returned an unusable shape, threw, or was needed. */
+'invalid-image' |
+/** A theme name outside the supported set. */
+'unknown-theme' |
+/** A fence language outside the loaded set. */
+'unknown-language' |
+/** An optional peer (`next`) is absent or not the expected shape. */
+'missing-peer' |
+/** The search index could not be fetched or parsed. */
+'search-index-unavailable' |
+/** The search-index route ran at request time instead of being prerendered. */
+'search-index-dynamic' |
+/** A code fence's meta string has a `title` that cannot be read. */
+'invalid-code-meta' |
+/** A plugin ran without the context this package always supplies. */
+'internal';
+/** An {@link Error} carrying a {@link DocsErrorCode}. */
+interface DocsError extends Error {
+  readonly code: DocsErrorCode;
+}
+/**
+ * Narrow an unknown caught value to one of this package's errors.
+ *
+ * Checks the prefix as well as the shape, so an unrelated `Error` that happens
+ * to carry a `code` — Node's own `ENOENT`, for one — is not mistaken for ours.
+ */
+declare function isDocsError(value: unknown): value is DocsError;
+//#endregion
+export { DOCS_ERROR_PREFIX, DocsError, DocsErrorCode, isDocsError };

package/dist/errors.js ADDED Viewed

@@ -0,0 +1,45 @@
+//#region src/errors.ts
+/**
+* The error taxonomy, as public API.
+*
+* Every failure this package raises is an `Error` whose message names the
+* package and which carries a `code` off this union. That exists so a host can
+* branch — downgrade broken-link failures in a preview build, say, or report
+* `invalid-frontmatter` differently from `missing-peer` — and until this
+* module was an entry point there was no supported way to do it. The taxonomy
+* said "branch on this" while the module said "you cannot import me", and the
+* two paragraphs contradicted each other for nineteen codes and forty-five
+* call sites.
+*
+* ```ts
+* import { isDocsError } from '@waveso/docs/errors';
+*
+* try {
+*   await docs.renderAll();
+* } catch (error) {
+*   if (isDocsError(error) && error.code === 'draft-link') {
+*     console.warn(error.message);
+*   } else {
+*     throw error;
+*   }
+* }
+* ```
+*
+* No class is exported, and that is deliberate: `instanceof` against a copy of
+* this module resolved twice — a monorepo with two versions installed, a
+* bundler that duplicates it — silently answers `false`. A string `code` and a
+* structural guard have no such failure mode.
+*/
+/** Prefix every message carries, so a stack trace names the culprit package. */
+const DOCS_ERROR_PREFIX = "@waveso/docs: ";
+/**
+* Narrow an unknown caught value to one of this package's errors.
+*
+* Checks the prefix as well as the shape, so an unrelated `Error` that happens
+* to carry a `code` — Node's own `ENOENT`, for one — is not mistaken for ours.
+*/
+function isDocsError(value) {
+	return value instanceof Error && typeof value.code === "string" && value.message.startsWith("@waveso/docs: ");
+}
+//#endregion
+export { DOCS_ERROR_PREFIX, isDocsError };

package/dist/frontmatter.d.ts CHANGED Viewed

@@ -6,10 +6,10 @@ import { StandardSchemaV1 } from "@standard-schema/spec";
  * The frontmatter fields the package itself understands, as a Zod schema.
  *
  * Optional fields use `.exactOptional()` rather than `.optional()` so the
- * inferred type is `{ description?: string }` and not
- * `{ description?: string | undefined }` — the latter is not assignable to
- * {@link DocFrontmatter} under `exactOptionalPropertyTypes`, and an explicit
- * `undefined` cannot come out of YAML anyway.
+ * inferred type is `{ description?: string }`: absent stays absent, which is
+ * the only thing YAML can express — there is no way to author an explicit
+ * `undefined` in a frontmatter block. A consumer's schema may still use plain
+ * `.optional()`; {@link DocFrontmatter} accepts both.
  *
  * `description` is deliberately not length-capped. The 155–160 character
  * advice for `<meta name="description">` is a pixel-width heuristic about
@@ -39,6 +39,17 @@ declare const docFrontmatterSchema: z.ZodObject<{
  * `raw` is whatever the YAML parser produced — `unknown` by construction, so
  * every field is checked rather than trusted.
  *
+ * The six fields this package reads are always parsed from the raw block by
+ * {@link docFrontmatterSchema} and laid back over the result, so a custom
+ * `schema` can only ever *add* fields. It cannot drop `draft`, `aliases`,
+ * `order`, `label`, `description` or `title` — which a bare
+ * `z.object({ title, audience })` silently does — and it cannot redefine them
+ * into a shape the sidebar, the redirects and the sitemap do not expect. The
+ * price is that a `.default()`, `.transform()` or `.coerce` aimed at one of the
+ * six is not honoured: the YAML wins. The return type intersects
+ * {@link DocFrontmatter} for the same reason — the built-ins are there whether
+ * or not the schema declared them.
+ *
  * Async because `~standard.validate` is allowed to return a promise and some
  * validators do (any schema with an async refinement). The source layer is
  * already async, so awaiting here costs nothing and refusing promises would
@@ -47,9 +58,30 @@ declare const docFrontmatterSchema: z.ZodObject<{
  * @param raw - Parsed YAML frontmatter block.
  * @param filePath - Path reported in the error. Pass the path the author
  *   would recognise (relative to the content root), not an absolute one.
- * @param schema - Optional replacement schema, normally
+ */
+declare function parseFrontmatter(raw: unknown, filePath: string): Promise<DocFrontmatter>;
+/**
+ * Validate one file's frontmatter against `schema`, or throw an error that
+ * names the file. See the two-argument overload for the contract.
+ *
+ * `TFrontmatter` comes from the schema and must never be named at the call
+ * site. That is what the two overloads buy: `parseFrontmatter<Mine>(raw, file)`
+ * with no schema is a compile error, where before it type-checked and then lied
+ * — nothing validated `Mine`, so its fields were `undefined` at runtime while
+ * typed as present.
+ *
+ * `undefined` is accepted here rather than the schema being optional so that a
+ * `DocsConfig<T>`'s own optional schema passes straight through. An earlier
+ * attempt made it required and broke exactly that, at `createDocsRoute` and at
+ * any consumer holding a typed config.
+ *
+ * @param raw - Parsed YAML frontmatter block.
+ * @param filePath - Path reported in the error. Pass the path the author
+ *   would recognise (relative to the content root), not an absolute one.
+ * @param schema - Replacement schema, normally
  *   `docFrontmatterSchema.extend(...)`. Any Standard Schema validator works.
+ *   `undefined` selects {@link docFrontmatterSchema}.
  */
-declare function parseFrontmatter<TFrontmatter extends DocFrontmatter = DocFrontmatter>(raw: unknown, filePath: string, schema?: StandardSchemaV1<unknown, TFrontmatter>): Promise<TFrontmatter>;
+declare function parseFrontmatter<TFrontmatter extends DocFrontmatter>(raw: unknown, filePath: string, schema: StandardSchemaV1<unknown, TFrontmatter> | undefined): Promise<TFrontmatter & DocFrontmatter>;
 //#endregion
-export { docFrontmatterSchema, parseFrontmatter };
+export { docFrontmatterSchema, parseFrontmatter, z };

package/dist/frontmatter.js CHANGED Viewed

@@ -1,13 +1,14 @@
+import { docsError } from "./docs-error.js";
 import { z } from "zod";
 //#region src/frontmatter.ts
 /**
 * The frontmatter fields the package itself understands, as a Zod schema.
 *
 * Optional fields use `.exactOptional()` rather than `.optional()` so the
-* inferred type is `{ description?: string }` and not
-* `{ description?: string | undefined }` — the latter is not assignable to
-* {@link DocFrontmatter} under `exactOptionalPropertyTypes`, and an explicit
-* `undefined` cannot come out of YAML anyway.
+* inferred type is `{ description?: string }`: absent stays absent, which is
+* the only thing YAML can express — there is no way to author an explicit
+* `undefined` in a frontmatter block. A consumer's schema may still use plain
+* `.optional()`; {@link DocFrontmatter} accepts both.
 *
 * `description` is deliberately not length-capped. The 155–160 character
 * advice for `<meta name="description">` is a pixel-width heuristic about
@@ -32,34 +33,60 @@ const docFrontmatterSchema = z.object({
 	order: z.number().exactOptional()
 });
 /**
-* Validate one file's frontmatter, or throw an error that names the file.
+* The package's own fields, every one of them optional, for the overlay pass
+* in {@link parseFrontmatter}.
 *
-* `raw` is whatever the YAML parser produced — `unknown` by construction, so
-* every field is checked rather than trusted.
-*
-* Async because `~standard.validate` is allowed to return a promise and some
-* validators do (any schema with an async refinement). The source layer is
-* already async, so awaiting here costs nothing and refusing promises would
-* have made a documented half of the spec silently unsupported.
-*
-* @param raw - Parsed YAML frontmatter block.
-* @param filePath - Path reported in the error. Pass the path the author
-*   would recognise (relative to the content root), not an absolute one.
-* @param schema - Optional replacement schema, normally
-*   `docFrontmatterSchema.extend(...)`. Any Standard Schema validator works.
+* `title` is optional here too, even though the package requires it: a custom
+* schema may legitimately produce a title the YAML does not carry (a
+* `.default()`), and demanding one of the raw block would fail that file. The
+* check after the merge reads the merged title instead, so both routes to a
+* title are accepted and no route to a missing one is.
 */
+const builtInFields = docFrontmatterSchema.partial();
 async function parseFrontmatter(raw, filePath, schema) {
 	const active = schema ?? docFrontmatterSchema;
 	let result;
 	try {
 		result = await active["~standard"].validate(raw ?? {});
 	} catch (error) {
-		throw new Error(`Invalid frontmatter in ${filePath}: the schema threw while validating it. This is a bug in the schema, not in the YAML — check any \`refine\`/\`transform\`/\`check\` it declares.`, { cause: error });
+		throw docsError("invalid-frontmatter", `Invalid frontmatter in ${filePath}: the schema threw while validating it. This is a bug in the schema, not in the YAML — check any \`refine\`/\`transform\`/\`check\` it declares.`, { cause: error });
 	}
-	if (result.issues === void 0) return result.value;
-	if (result.issues.length === 0) throw new Error(`Invalid frontmatter in ${filePath}: the schema rejected it but reported no issues, so there is nothing to act on. This is a bug in the schema.`);
-	const details = result.issues.map((issue) => `  - ${formatIssuePath(issue.path)}: ${issue.message}`).join("\n");
-	throw new Error(`Invalid frontmatter in ${filePath}:\n${details}\n${schema === void 0 ? "Fix the YAML block at the top of that file." : "Fix the YAML block at the top of that file, or the `frontmatterSchema` in your docs config."}`);
+	if (result.issues === void 0) return active === docFrontmatterSchema ? result.value : applyBuiltIns(result.value, raw, filePath);
+	if (result.issues.length === 0) throw docsError("invalid-frontmatter", `Invalid frontmatter in ${filePath}: the schema rejected it but reported no issues, so there is nothing to act on. This is a bug in the schema.`);
+	const source = schema === void 0 ? "Fix the YAML block at the top of that file." : "Fix the YAML block at the top of that file, or the `frontmatterSchema` in your docs config.";
+	throw docsError("invalid-frontmatter", `Invalid frontmatter in ${filePath}:\n${formatIssues(result.issues)}\n${source}`);
+}
+/**
+* Re-read the package's own fields from the raw block and lay them back over a
+* custom schema's output.
+*
+* Without this, the guarantee that a `frontmatterSchema` keeps the built-ins
+* rests on `TFrontmatter extends DocFrontmatter` — which constrains `title` and
+* nothing else, because the other five fields are optional. So
+* `z.object({ title, audience })`, written from scratch instead of as
+* `docFrontmatterSchema.extend(...)`, type-checks and then strips `draft`,
+* `aliases`, `order` and `label` on the way through. The package reads the
+* absence as "not a draft, no redirects, no order": an unpublished page ships,
+* is linked from the sidebar and is submitted to Google in the sitemap, and
+* every renamed page 404s. `tsc` reports nothing, at either end.
+*
+* The overlay runs after the custom schema rather than instead of it, so a
+* stricter rule on a built-in (`title: z.string().max(60)`) still fails the
+* build — it just cannot change the value the package then reads.
+*/
+async function applyBuiltIns(value, raw, filePath) {
+	const result = await builtInFields["~standard"].validate(raw ?? {});
+	if (result.issues !== void 0) throw docsError("invalid-frontmatter", `Invalid frontmatter in ${filePath}:\n${formatIssues(result.issues)}\n@waveso/docs reads these fields itself, so they are validated even when your \`frontmatterSchema\` does not declare them. Fix the YAML block at the top of that file.`);
+	const merged = {
+		...value,
+		...result.value
+	};
+	if (typeof merged.title !== "string" || merged.title.length === 0) throw docsError("invalid-frontmatter", `Invalid frontmatter in ${filePath}: no \`title\`. Every page needs one — it drives the \`<h1>\` fallback, \`<title>\`, the sidebar and search. Add \`title:\` to the YAML block at the top of that file, or give your \`frontmatterSchema\` a title it can supply.`);
+	return merged;
+}
+/** Render a validator's issues as the bullet list under the file name. */
+function formatIssues(issues) {
+	return issues.map((issue) => `  - ${formatIssuePath(issue.path)}: ${issue.message}`).join("\n");
 }
 /**
 * Render an issue path as `aliases[0]` / `title`, never as `""`.
@@ -77,4 +104,4 @@ function formatIssuePath(path) {
 	}, "");
 }
 //#endregion
-export { docFrontmatterSchema, parseFrontmatter };
+export { docFrontmatterSchema, parseFrontmatter, z };

package/dist/highlighter.d.ts CHANGED Viewed

@@ -81,9 +81,9 @@ interface DocsHighlighterOptions {
    * than a build-time throw. The runtime check below stays for JavaScript
    * callers and for values that arrive from JSON config.
    */
-  langs?: readonly DocsLang[];
+  langs?: readonly DocsLang[] | undefined;
   /** Theme pair. Defaults to {@link DEFAULT_DOCS_THEMES}. */
-  themes?: DocsThemes;
+  themes?: DocsThemes | undefined;
 }
 /**
  * Create (or reuse) the process-wide highlighter for a given option set.

package/dist/highlighter.js CHANGED Viewed

@@ -1,3 +1,4 @@
+import { docsError } from "./docs-error.js";
 import { createHighlighterCore } from "shiki/core";
 import { createJavaScriptRegexEngine } from "shiki/engine/javascript";
 //#region src/highlighter.ts
@@ -155,11 +156,11 @@ function isDocsTheme(name) {
 function createDocsHighlighter(options = {}) {
 	const themes = options.themes ?? DEFAULT_DOCS_THEMES;
 	const requested = options.langs ?? DEFAULT_DOCS_LANGS;
-	for (const theme of [themes.light, themes.dark]) if (!isDocsTheme(theme)) throw new Error(`@waveso/docs: unknown Shiki theme '${theme}'. Supported themes: ${Object.keys(THEME_LOADERS).sort().join(", ")}. To use another theme, pass your own highlighter to createDocsRenderer().`);
+	for (const theme of [themes.light, themes.dark]) if (!isDocsTheme(theme)) throw docsError("unknown-theme", `@waveso/docs: unknown Shiki theme '${theme}'. Supported themes: ${Object.keys(THEME_LOADERS).sort().join(", ")}. To use another theme, pass your own highlighter to createDocsRenderer().`);
 	const langs = [...new Set(requested)].sort();
 	const loaders = /* @__PURE__ */ new Set();
 	for (const lang of langs) {
-		if (!isDocsLang(lang)) throw new Error(`@waveso/docs: unknown code language '${lang}'. Supported languages: ${Object.keys(LANG_LOADERS).sort().join(", ")}. To use another grammar, pass your own highlighter to createDocsRenderer().`);
+		if (!isDocsLang(lang)) throw docsError("unknown-language", `@waveso/docs: unknown code language '${lang}'. Supported languages: ${Object.keys(LANG_LOADERS).sort().join(", ")}. To use another grammar, pass your own highlighter to createDocsRenderer().`);
 		loaders.add(LANG_LOADERS[lang]);
 	}
 	const key = JSON.stringify({