@tsdoctor/pages 0.1.0

package/index.d.ts

@@ -0,0 +1,1193 @@
+import { FlowContent, MarkdownStringifyError, PhrasingContent } from "@effected/markdown";
+import { Effect, Option, Result, Schema } from "effect";
+import { ApiItem, ApiItemKind, ApiPackage } from "@microsoft/api-extractor-model";
+import { ApiItems, CrossLinker, ImportStatement, Routes } from "@tsdoctor/model";
+//#region src/Blocks.d.ts
+/**
+ * A run of block-level mdast — a summary paragraph, a remarks section.
+ *
+ * @public
+ */
+declare const Prose: Schema.$Array<Schema.Codec<FlowContent, FlowContent, never, never>>;
+/**
+ * A run of inline mdast — a one-line description, a table cell, a
+ * deprecation message.
+ *
+ * @public
+ */
+declare const Inline: Schema.$Array<Schema.Codec<PhrasingContent, PhrasingContent, never, never>>;
+/**
+ * The TSDoc release tag a page's title badge is derived from.
+ *
+ * @public
+ */
+declare const ReleaseTag: Schema.Literals<readonly ["Public", "Beta", "Alpha", "Internal"]>;
+declare const CodeText_base: Schema.Class<CodeText, Schema.Struct<{
+  /** The directive-stripped text a reader sees and copies. */
+  readonly display: Schema.String;
+  /** The type-check text: hidden imports, cut marker, directives intact. */
+  readonly source: Schema.String;
+}>, {}>;
+/**
+ * The two spellings of one code block: what a reader sees and what the
+ * type-checker sees.
+ *
+ * @remarks
+ * `source` is the type-check text — hidden `import type` lines, then
+ * `// ---cut---`, then the code, Twoslash directives intact. `display` is
+ * the directive-stripped text a reader sees and copies. RSPress spends them
+ * as two props; VitePress puts `source` in a `ts twoslash` fence and lets the
+ * cut marker hide the preamble. Carrying both is one field of redundancy
+ * against a transformer per framework.
+ *
+ * @public
+ */
+declare class CodeText extends CodeText_base {}
+declare const ParameterRow_base: Schema.Class<ParameterRow, Schema.Struct<{
+  /** The parameter name as declared. */
+  readonly name: Schema.String;
+  /** The parameter's type text from the declaration excerpt, when the declaration carries one. */
+  readonly type: Schema.optionalKey<Schema.String>;
+  /** The `@param` description, cross-linked. */
+  readonly description: Schema.$Array<Schema.Codec<PhrasingContent, PhrasingContent, never, never>>;
+}>, {}>;
+/**
+ * One row of a parameters table.
+ *
+ * @public
+ */
+declare class ParameterRow extends ParameterRow_base {}
+declare const EnumMemberRow_base: Schema.Class<EnumMemberRow, Schema.Struct<{
+  /** The member name. */
+  readonly name: Schema.String;
+  /** The initializer value, when the declaration carries one. */
+  readonly value: Schema.optionalKey<Schema.String>;
+  /** The member's summary, cross-linked. */
+  readonly description: Schema.$Array<Schema.Codec<PhrasingContent, PhrasingContent, never, never>>;
+}>, {}>;
+/**
+ * One row of an enum members table.
+ *
+ * @public
+ */
+declare class EnumMemberRow extends EnumMemberRow_base {}
+/**
+ * The role a class or interface member plays, which decides its heading
+ * group and how an emitter labels it.
+ *
+ * @public
+ */
+declare const MemberRole: Schema.Literals<readonly ["constructor", "property", "method", "getter", "call-signature", "construct-signature", "index-signature"]>;
+declare const Member_base: Schema.Class<Member, Schema.Struct<{
+  /** Which heading group the member belongs to and how it is labelled. */
+  readonly role: Schema.Literals<readonly ["constructor", "property", "method", "getter", "call-signature", "construct-signature", "index-signature"]>;
+  /** The member's display name (`constructor` for constructors). */
+  readonly name: Schema.String;
+  /** The anchor id, computed once by the model's member-anchor algorithm. */
+  readonly anchor: Schema.String;
+  /** The member signature in its owner's context. */
+  readonly code: typeof CodeText;
+  /** The member's summary, cross-linked. */
+  readonly summary: Schema.optionalKey<Schema.$Array<Schema.Codec<PhrasingContent, PhrasingContent, never, never>>>;
+  /** The member's parameters, when it has any. */
+  readonly parameters: Schema.optionalKey<Schema.$Array<typeof ParameterRow>>;
+  /** The `@returns` description, cross-linked. */
+  readonly returns: Schema.optionalKey<Schema.$Array<Schema.Codec<PhrasingContent, PhrasingContent, never, never>>>;
+}>, {}>;
+/**
+ * One member of a class or interface: its own signature, summary and the
+ * anchor id every cross-link to it resolves against.
+ *
+ * @remarks
+ * `anchor` arrives as data from `ApiItems.memberAnchors` in
+ * `@tsdoctor/model`, threaded through the work item. No emitter recomputes
+ * it — the route map's `#fragment` and the page's element id must come from
+ * one computation, or cross-links land nowhere.
+ *
+ * @public
+ */
+declare class Member extends Member_base {}
+declare const Example_base: Schema.Class<Example, Schema.Struct<{
+  /** The fence language after normalization (`typescript` for TS/JS). */
+  readonly language: Schema.String;
+  /** The formatted example. */
+  readonly code: typeof CodeText;
+  /** Whether the example is handed to Twoslash. */
+  readonly typeChecked: Schema.Boolean;
+}>, {}>;
+/**
+ * One example: its language, its code and whether it is type-checked.
+ *
+ * @remarks
+ * A non-TypeScript example is never type-checked; emitters render its
+ * `display` in a plain fence. A type-checked example carries the `@noErrors`
+ * directive and the package import in `source`.
+ *
+ * @public
+ */
+declare class Example extends Example_base {}
+declare const MemberIndexEntry_base: Schema.Class<MemberIndexEntry, Schema.Struct<{
+  /** The member's display name. */
+  readonly name: Schema.String;
+  /** The route of the member's own page. */
+  readonly route: Schema.String;
+  /** The member's summary, cross-linked. */
+  readonly summary: Schema.optionalKey<Schema.$Array<Schema.Codec<PhrasingContent, PhrasingContent, never, never>>>;
+}>, {}>;
+/**
+ * One entry in a namespace page's member index.
+ *
+ * @public
+ */
+declare class MemberIndexEntry extends MemberIndexEntry_base {}
+declare const Title_base: Schema.Class<Title, Schema.Struct<{
+  readonly kind: Schema.tag<"title">;
+  /** The item's display name. */
+  readonly name: Schema.String;
+  /** The release tag; emitters badge anything other than `Public`. */
+  readonly releaseTag: Schema.Literals<readonly ["Public", "Beta", "Alpha", "Internal"]>;
+  /** The `@deprecated` message, cross-linked, when present. */
+  readonly deprecation: Schema.optionalKey<Schema.$Array<Schema.Codec<PhrasingContent, PhrasingContent, never, never>>>;
+}>, {}>;
+/**
+ * The page title, with the release-tag badge and deprecation notice that
+ * render beside it.
+ *
+ * @public
+ */
+declare class Title extends Title_base {}
+declare const AvailableFrom_base: Schema.Class<AvailableFrom, Schema.Struct<{
+  readonly kind: Schema.tag<"available-from">;
+  /** The package name the entry points are spelled under. */
+  readonly packageName: Schema.String;
+  /** Entry point names; `default` denotes the package root. */
+  readonly entryPoints: Schema.$Array<Schema.String>;
+}>, {}>;
+/**
+ * The "Available from" line for an item exported from several entry points.
+ *
+ * @public
+ */
+declare class AvailableFrom extends AvailableFrom_base {}
+/**
+ * The role a prose block plays, which decides whether an emitter gives it a
+ * heading and what the heading says.
+ *
+ * @public
+ */
+declare const ProseRole: Schema.Literals<readonly ["summary", "remarks", "returns"]>;
+declare const ProseBlock_base: Schema.Class<ProseBlock, Schema.Struct<{
+  readonly kind: Schema.tag<"prose">;
+  /** Which section this is. */
+  readonly role: Schema.Literals<readonly ["summary", "remarks", "returns"]>;
+  /** The section body, cross-linked. */
+  readonly content: Schema.$Array<Schema.Codec<FlowContent, FlowContent, never, never>>;
+}>, {}>;
+/**
+ * A prose section: the summary, the remarks, a function's returns.
+ *
+ * @public
+ */
+declare class ProseBlock extends ProseBlock_base {}
+declare const SourceLink_base: Schema.Class<SourceLink, Schema.Struct<{
+  readonly kind: Schema.tag<"source-link">;
+  /** The resolved source URL. */
+  readonly href: Schema.String;
+}>, {}>;
+/**
+ * The link to the item's source code.
+ *
+ * @public
+ */
+declare class SourceLink extends SourceLink_base {}
+declare const Signature_base: Schema.Class<Signature, Schema.Struct<{
+  readonly kind: Schema.tag<"signature">;
+  /** The signature text pair. */
+  readonly code: typeof CodeText;
+  /** Whether a parameters table follows directly (functions). */
+  readonly hasParameters: Schema.optionalKey<Schema.Boolean>;
+  /** Whether a members table follows directly (enums). */
+  readonly hasMembers: Schema.optionalKey<Schema.Boolean>;
+}>, {}>;
+/**
+ * The item's full signature block — a function signature, a class or
+ * interface skeleton listing every member, an enum with its members.
+ *
+ * @public
+ */
+declare class Signature extends Signature_base {}
+declare const BaseClass_base: Schema.Class<BaseClass, Schema.Struct<{
+  readonly kind: Schema.tag<"base-class">;
+  /** The exported class. */
+  readonly className: Schema.String;
+  /** The unexported base declaration's name. */
+  readonly baseName: Schema.String;
+  /** The package the base is not exported from. */
+  readonly packageName: Schema.String;
+  /** The base declaration's signature. */
+  readonly code: typeof CodeText;
+}>, {}>;
+/**
+ * The inline "Base Class" section for a synthetic base declaration — the
+ * unexported `Foo_base` an exported class extends.
+ *
+ * @remarks
+ * The section heading slugs to `SyntheticBases.BASE_CLASS_ANCHOR` in
+ * `@tsdoctor/model`, which is where the base name's cross-link route points.
+ *
+ * @public
+ */
+declare class BaseClass extends BaseClass_base {}
+declare const MemberGroup_base: Schema.Class<MemberGroup, Schema.Struct<{
+  readonly kind: Schema.tag<"member-group">;
+  /** The group heading. */
+  readonly title: Schema.String;
+  /** The members, in declaration order. */
+  readonly members: Schema.$Array<typeof Member>;
+}>, {}>;
+/**
+ * A heading group of members — "Constructors", "Static Methods",
+ * "Properties", "Call Signatures" — in the order the page lists them.
+ *
+ * @public
+ */
+declare class MemberGroup extends MemberGroup_base {}
+declare const ParameterTable_base: Schema.Class<ParameterTable, Schema.Struct<{
+  readonly kind: Schema.tag<"parameters">;
+  /** The rows, in declaration order. */
+  readonly rows: Schema.$Array<typeof ParameterRow>;
+}>, {}>;
+/**
+ * A parameters table at page level — a function's parameters, adjacent to
+ * its signature.
+ *
+ * @public
+ */
+declare class ParameterTable extends ParameterTable_base {}
+declare const EnumMemberTable_base: Schema.Class<EnumMemberTable, Schema.Struct<{
+  readonly kind: Schema.tag<"enum-members">;
+  /** The rows, in declaration order. */
+  readonly rows: Schema.$Array<typeof EnumMemberRow>;
+}>, {}>;
+/**
+ * An enum's members table, adjacent to its signature.
+ *
+ * @public
+ */
+declare class EnumMemberTable extends EnumMemberTable_base {}
+declare const ExampleGroup_base: Schema.Class<ExampleGroup, Schema.Struct<{
+  readonly kind: Schema.tag<"examples">;
+  /** The examples, in TSDoc order. */
+  readonly items: Schema.$Array<typeof Example>;
+}>, {}>;
+/**
+ * The "Examples" section.
+ *
+ * @public
+ */
+declare class ExampleGroup extends ExampleGroup_base {}
+declare const SeeAlso_base: Schema.Class<SeeAlso, Schema.Struct<{
+  readonly kind: Schema.tag<"see-also">;
+  /** The references, in TSDoc order. */
+  readonly references: Schema.$Array<Schema.$Array<Schema.Codec<PhrasingContent, PhrasingContent, never, never>>>;
+}>, {}>;
+/**
+ * The "See Also" section — one cross-linked reference per `@see` tag.
+ *
+ * @public
+ */
+declare class SeeAlso extends SeeAlso_base {}
+declare const MemberIndex_base: Schema.Class<MemberIndex, Schema.Struct<{
+  readonly kind: Schema.tag<"member-index">;
+  /** The section heading. */
+  readonly title: Schema.String;
+  /** The entries, in declaration order. */
+  readonly entries: Schema.$Array<typeof MemberIndexEntry>;
+}>, {}>;
+/**
+ * A namespace page's index of one member kind — "Classes", "Functions" —
+ * linking to each member's own page.
+ *
+ * @public
+ */
+declare class MemberIndex extends MemberIndex_base {}
+/**
+ * The closed vocabulary: every block a page may carry.
+ *
+ * @remarks
+ * Narrow on `kind`. Construct the variant classes rather than the union's
+ * inherited `make`, which typechecks against every member and yields a
+ * many-branch error when it fails.
+ *
+ * @public
+ */
+declare const Block: Schema.Union<readonly [typeof Title, typeof AvailableFrom, typeof ProseBlock, typeof SourceLink, typeof Signature, typeof BaseClass, typeof MemberGroup, typeof ParameterTable, typeof EnumMemberTable, typeof ExampleGroup, typeof SeeAlso, typeof MemberIndex]>;
+/**
+ * A block instance — one member of the `Block` union.
+ *
+ * @public
+ */
+type Block = typeof Block.Type;
+/**
+ * The discriminant values of the `Block` union.
+ *
+ * @public
+ */
+type BlockKind = Block["kind"];
+//#endregion
+//#region src/Examples.d.ts
+declare const ExampleFormatError_base: Schema.Class<ExampleFormatError, Schema.TaggedStruct<"ExampleFormatError", {
+  /** The fence language the parser was chosen for. */
+  readonly language: Schema.String;
+  /** The original Prettier error. */
+  readonly cause: Schema.Defect;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Prettier could not format an example.
+ *
+ * @remarks
+ * Malformed example code is author input, so this is a typed failure rather
+ * than a defect. The original Prettier error rides in `cause` rather than
+ * being flattened to a string; an adapter that reports it (the RSPress
+ * `PrettierError` event) reads the message from there and falls back to the
+ * unformatted code.
+ *
+ * @public
+ */
+declare class ExampleFormatError extends ExampleFormatError_base {
+  get message(): string;
+}
+/**
+ * A raw example as extracted from TSDoc.
+ *
+ * @public
+ */
+interface RawExample {
+  /** The fence language as written. */
+  readonly language: string;
+  /** The fence body. */
+  readonly code: string;
+}
+/**
+ * An example prepared for Twoslash: the import line and the `@noErrors`
+ * directive added, and the language normalized.
+ *
+ * @public
+ */
+interface PreparedExample {
+  /** The code with the package import and directives prepended. */
+  readonly code: string;
+  /** Whether the example is TypeScript/JavaScript and therefore type-checked. */
+  readonly isTypeScript: boolean;
+  /** The normalized language: `typescript` for TS/JS, otherwise as written. */
+  readonly language: string;
+}
+/**
+ * Prepare an example for Twoslash: prepend `import { name } from "pkg"`
+ * unless the example already imports the package, and prepend `// @noErrors`
+ * when errors are suppressed. Non-TypeScript examples pass through untouched.
+ *
+ * @param example - The example with language and code
+ * @param apiItemName - The documented item, imported at the top of the example
+ * @param packageName - The package to import it from
+ * @param suppressErrors - Whether to suppress TypeScript errors (default `true`)
+ * @public
+ */
+declare function prepareExampleCode(example: RawExample, apiItemName: string, packageName: string, suppressErrors?: boolean): PreparedExample;
+/**
+ * Strip Twoslash directives from code for display: config directives
+ * (`// @noErrors`, `// @errors: 2304`, `// @filename: …`), annotation markers
+ * (`// ^?`) and the cut directives — `// ---cut---` removes itself and every
+ * line before it, `// ---cut-after---` itself and every line after, and a
+ * `// ---cut-start---` / `// ---cut-end---` pair removes the range between.
+ *
+ * @param code - The code containing Twoslash directives
+ * @returns The code a reader sees and copies
+ * @public
+ */
+declare function stripTwoslashDirectives(code: string): string;
+/**
+ * Prepend hidden imports to code using the Twoslash cut directive, so the
+ * type-checker resolves external types while the reader never sees the
+ * import lines. Returns the code unchanged when there is nothing to import.
+ *
+ * @param code - The code to prepend imports to
+ * @param imports - The import statements to add
+ * @public
+ */
+declare function prependHiddenImports(code: string, imports: ReadonlyArray<ImportStatement>): string;
+/**
+ * Build both spellings of a code block from its type-check text: the
+ * `source` as given, the `display` with every directive stripped.
+ *
+ * @param source - The type-check text — hidden imports, cut marker, directives intact
+ * @public
+ */
+declare function codeText(source: string): CodeText;
+/**
+ * Add logical blank lines between code sections for visual clarity: after an
+ * import block, before a section comment and before a `return`.
+ *
+ * @remarks
+ * Runs after Prettier, which does not insert breathing room of its own. Lines
+ * inside a multi-line import and Twoslash directive lines never trigger a
+ * rule, so a directive stays attached to the line it annotates.
+ *
+ * @param code - Prettier-formatted code
+ * @public
+ */
+declare function addLogicalBlankLines(code: string): string;
+/**
+ * Format example code with Prettier, then add logical blank lines. A
+ * language Prettier has no parser for is returned unchanged.
+ *
+ * @param code - The code to format
+ * @param language - The fence language (`typescript`, `ts`, `js`, …)
+ * @public
+ */
+declare const formatExampleCode: (code: string, language: string) => Effect.Effect<string, ExampleFormatError>;
+/**
+ * Build an {@link Example} block item from a raw TSDoc example: prepare it
+ * for Twoslash, format it, and produce both code spellings once.
+ *
+ * @remarks
+ * A non-TypeScript example is not type-checked, so its `display` and
+ * `source` are the same formatted text and emitters render it in a plain
+ * fence.
+ *
+ * @param example - The example with language and code
+ * @param apiItemName - The documented item, imported at the top of the example
+ * @param packageName - The package to import it from
+ * @param suppressErrors - Whether to suppress TypeScript errors (default `true`)
+ * @public
+ */
+declare const buildExample: (example: RawExample, apiItemName: string, packageName: string, suppressErrors?: boolean) => Effect.Effect<Example, ExampleFormatError>;
+//#endregion
+//#region src/Nav.d.ts
+declare const NavEntry_base: Schema.Class<NavEntry, Schema.Struct<{
+  /** The category key the page was categorized under. */
+  readonly categoryKey: Schema.String;
+  /** The sidebar label — the display name, qualified for a namespace member. */
+  readonly label: Schema.String;
+  /** The file basename without extension (`foo` for `class/foo.mdx`). */
+  readonly name: Schema.String;
+  /** The page route. */
+  readonly route: Schema.String;
+}>, {}>;
+/**
+ * A page's place in the navigation tree, carried on the page itself.
+ *
+ * @public
+ */
+declare class NavEntry extends NavEntry_base {}
+declare const NavCategory_base: Schema.Class<NavCategory, Schema.Struct<{
+  /** The group label. */
+  readonly displayName: Schema.String;
+  /** The folder the category's pages live in. */
+  readonly folderName: Schema.String;
+  /** Whether the group can be collapsed; absent means the renderer's default. */
+  readonly collapsible: Schema.optionalKey<Schema.Boolean>;
+  /** Whether the group starts collapsed; absent means the renderer's default. */
+  readonly collapsed: Schema.optionalKey<Schema.Boolean>;
+  /** Heading depths surfaced in an overview; absent means the renderer's default. */
+  readonly overviewHeaders: Schema.optionalKey<Schema.$Array<Schema.Number>>;
+}>, {}>;
+/**
+ * The per-category presentation facts a tree carries for its groups.
+ *
+ * @public
+ */
+declare class NavCategory extends NavCategory_base {}
+declare const NavPage_base: Schema.Class<NavPage, Schema.Struct<{
+  /** The sidebar label. */
+  readonly label: Schema.String;
+  /** The file basename without extension. */
+  readonly name: Schema.String;
+  /** The page route. */
+  readonly route: Schema.String;
+}>, {}>;
+/**
+ * One page in a group.
+ *
+ * @public
+ */
+declare class NavPage extends NavPage_base {}
+declare const NavGroup_base: Schema.Class<NavGroup, Schema.Struct<{
+  /** The category key. */
+  readonly key: Schema.String;
+  /** The category presentation facts. */
+  readonly category: typeof NavCategory;
+  /** The group's pages, sorted by label. */
+  readonly pages: Schema.$Array<typeof NavPage>;
+}>, {}>;
+/**
+ * One category group with its pages, already sorted.
+ *
+ * @public
+ */
+declare class NavGroup extends NavGroup_base {}
+declare const NavTree_base: Schema.Class<NavTree, Schema.Struct<{
+  /** The API's base route; the index page lives at its root. */
+  readonly baseRoute: Schema.String;
+  /** The index page. */
+  readonly index: typeof NavPage;
+  /** The category groups that received at least one page, in category order. */
+  readonly groups: Schema.$Array<typeof NavGroup>;
+}>, {}>;
+/**
+ * The navigation tree for one API.
+ *
+ * @public
+ */
+declare class NavTree extends NavTree_base {}
+/**
+ * The input to {@link buildNav}.
+ *
+ * @public
+ */
+interface BuildNavInput {
+  /** The API's base route. */
+  readonly baseRoute: string;
+  /** The categories in the order they were configured — insertion order is the group order. */
+  readonly categories: Readonly<Record<string, NavCategory>>;
+  /** Every generated page's entry, in any order. */
+  readonly entries: ReadonlyArray<NavEntry>;
+}
+/**
+ * The label of the index page every tree carries.
+ *
+ * @public
+ */
+declare const NAV_INDEX_LABEL = "API Reference";
+/**
+ * Sort pages the way the sidebar lists them: alphabetically by label.
+ *
+ * @public
+ */
+declare function sortNavPages(pages: ReadonlyArray<NavPage>): ReadonlyArray<NavPage>;
+/**
+ * Build the navigation tree for one API from its categories and its pages.
+ *
+ * @remarks
+ * Groups follow `categories`' insertion order and a category with no page
+ * is dropped rather than rendered empty. An entry whose category key names
+ * no configured category is dropped too — it could not have been generated
+ * into a folder — so the tree only ever describes pages that exist.
+ *
+ * @public
+ */
+declare function buildNav(input: BuildNavInput): NavTree;
+//#endregion
+//#region src/Page.d.ts
+/**
+ * The neutral head tag, as a schema — the same shape as `@tsdoctor/seo`'s
+ * `HeadTag` interface, so a value from `headTags` is accepted unchanged.
+ *
+ * @public
+ */
+declare const HeadTag: Schema.Struct<{
+  /** The element name. */
+  readonly tag: Schema.Literals<readonly ["meta", "link", "script"]>;
+  /** The element attributes. */
+  readonly attrs: Schema.$Record<Schema.String, Schema.String>;
+  /** Element content; only meaningful for `script`. */
+  readonly body: Schema.optionalKey<Schema.String>;
+}>;
+/**
+ * A neutral head tag value.
+ *
+ * @public
+ */
+type HeadTag = typeof HeadTag.Type;
+/**
+ * The kind of symbol a page documents — which builder produced it, and
+ * which component imports and block layout an emitter chooses.
+ *
+ * @public
+ */
+declare const PageKind: Schema.Literals<readonly ["class", "interface", "function", "type-alias", "enum", "variable", "namespace"]>;
+/**
+ * A page kind value.
+ *
+ * @public
+ */
+type PageKind = typeof PageKind.Type;
+declare const Page_base: Schema.Class<Page, Schema.Struct<{
+  /** The kind of symbol the page documents. */
+  readonly kind: Schema.Literals<readonly ["class", "interface", "function", "type-alias", "enum", "variable", "namespace"]>;
+  /** The documented item's display name — the first title part. */
+  readonly entityName: Schema.String;
+  /** The category's singular name (`Class`, `Function`) — the second title part. */
+  readonly singularName: Schema.String;
+  /** The API's display name — the last title part, when the site names one. */
+  readonly apiName: Schema.optionalKey<Schema.String>;
+  /** The page description: the item's summary, or the fallback the generators used. */
+  readonly description: Schema.String;
+  /** The page route. */
+  readonly route: Schema.String;
+  /** Every `<head>` tag the page carries, from `@tsdoctor/seo`. */
+  readonly headTags: Schema.$Array<Schema.Struct<{
+    /** The element name. */
+    readonly tag: Schema.Literals<readonly ["meta", "link", "script"]>;
+    /** The element attributes. */
+    readonly attrs: Schema.$Record<Schema.String, Schema.String>;
+    /** Element content; only meaningful for `script`. */
+    readonly body: Schema.optionalKey<Schema.String>;
+  }>>;
+  /** The page body, in order. */
+  readonly blocks: Schema.$Array<Schema.Union<readonly [typeof Title, typeof AvailableFrom, typeof ProseBlock, typeof SourceLink, typeof Signature, typeof BaseClass, typeof MemberGroup, typeof ParameterTable, typeof EnumMemberTable, typeof ExampleGroup, typeof SeeAlso, typeof MemberIndex]>>;
+  /** The page's place in the navigation tree. */
+  readonly nav: typeof NavEntry;
+}>, {}>;
+/**
+ * One generated API page.
+ *
+ * @public
+ */
+declare class Page extends Page_base {
+  /**
+   * The structured page title: `{entityName} | {singularName} | API | {apiName}`,
+   * the last part omitted when the site names no API.
+   */
+  get title(): string;
+}
+//#endregion
+//#region src/Build.d.ts
+/**
+ * The description a page carries when its item has no summary.
+ *
+ * @public
+ */
+declare const NO_DESCRIPTION = "No description available.";
+/**
+ * A member of a namespace, as the adapter's work item carries it: the
+ * qualified name decides the page route and the sidebar label.
+ *
+ * @public
+ */
+interface NamespaceMemberFacts {
+  /** `Namespace.member`, as the route's last segment and the nav label. */
+  readonly qualifiedName: string;
+}
+/**
+ * The input to {@link buildPage}: the item plus every fact the adapter's
+ * work item and API configuration contribute.
+ *
+ * @public
+ */
+interface BuildPageInput {
+  /** The documented item. */
+  readonly item: ApiItem;
+  /** The category key the item was categorized under. */
+  readonly categoryKey: string;
+  /** The category's singular name — the second title part. */
+  readonly singularName: string;
+  /** The category folder the page lives in. */
+  readonly folderName: string;
+  /** The API's base route. */
+  readonly baseRoute: string;
+  /** The package name examples import from and "Available from" spells. */
+  readonly packageName: string;
+  /** The API's display name — the last title part, when the site names one. */
+  readonly apiName?: string | undefined;
+  /** Present when the item is a namespace member documented on its own page. */
+  readonly namespaceMember?: NamespaceMemberFacts | undefined;
+  /** Entry points the item is exported from; more than one yields an "Available from" line. */
+  readonly availableFrom?: ReadonlyArray<string> | undefined;
+  /** The unexported base declaration a class extends, rendered inline. */
+  readonly syntheticBase?: ApiItem | undefined;
+  /** Anchor id per member, keyed by canonical reference, from `ApiItems.memberAnchors`. */
+  readonly memberAnchors?: ReadonlyMap<string, string> | undefined;
+  /** The source repository, when the site links to it. */
+  readonly source?: ApiItems.SourceLinkTarget | undefined;
+  /** Whether examples carry `@noErrors`; defaults to `true`. */
+  readonly suppressExampleErrors?: boolean | undefined;
+  /** The cross-linker built from the API's route map. */
+  readonly linker: CrossLinker;
+  /** Head tags for the page, when the adapter has them before building. */
+  readonly headTags?: ReadonlyArray<HeadTag> | undefined;
+  /**
+   * Called when Prettier cannot format an example; the example then carries
+   * its unformatted code. Absent, the failure is silent.
+   */
+  readonly onExampleFormatError?: ((error: ExampleFormatError) => Effect.Effect<void>) | undefined;
+}
+/**
+ * The input to {@link buildIndexPage}.
+ *
+ * @public
+ */
+interface BuildIndexPageInput {
+  /** The package the index introduces. */
+  readonly packageName: string;
+  /** The API's base route; the index lives at its root. */
+  readonly baseRoute: string;
+}
+declare const IndexPage_base: Schema.Class<IndexPage, Schema.Struct<{
+  /** The page route (`{baseRoute}/index`). */
+  readonly route: Schema.String;
+  /** The page title. */
+  readonly title: Schema.String;
+  /** The page description. */
+  readonly description: Schema.String;
+}>, {}>;
+/**
+ * The API landing page: frontmatter facts only, no blocks.
+ *
+ * @public
+ */
+declare class IndexPage extends IndexPage_base {}
+/**
+ * The label of the index page.
+ *
+ * @public
+ */
+declare const INDEX_PAGE_TITLE = "API Reference";
+/**
+ * Build the API landing page.
+ *
+ * @public
+ */
+declare function buildIndexPage(input: BuildIndexPageInput): IndexPage;
+/**
+ * Whether {@link buildPage} produces a page for an item of this kind.
+ *
+ * @public
+ */
+declare function isPageKind(kind: ApiItemKind): boolean;
+/**
+ * Build the page for one item, or none for an item kind that gets no page.
+ *
+ * @remarks
+ * The route is `{baseRoute}/{folderName}/{name}` with the name lowercased;
+ * a namespace member's last segment is its lowercased qualified name, which
+ * is also its sidebar label. Only Prettier can fail here, and that failure
+ * degrades through {@link BuildPageInput.onExampleFormatError}, so the
+ * error channel is `never`.
+ *
+ * @public
+ */
+declare const buildPage: (input: BuildPageInput) => Effect.Effect<Option.Option<Page>>;
+//#endregion
+//#region src/Llms.d.ts
+/**
+ * A parsed link entry from llms.txt format.
+ *
+ * @example
+ * ```text
+ * - [Page Title](/path/to/page): Page description
+ * ```
+ *
+ * @public
+ */
+interface LlmsTxtEntry {
+  title: string;
+  url: string;
+  description: string | undefined;
+}
+/**
+ * A pointer to a per-package llms.txt file, appended to the global llms.txt.
+ *
+ * @public
+ */
+interface PackagePointer {
+  name: string;
+  llmsTxtUrl: string;
+}
+/**
+ * Input for generating a per-package llms.txt index.
+ *
+ * @public
+ */
+interface PackageLlmsTxtInput {
+  name: string;
+  packageName: string;
+  guidePages: LlmsTxtEntry[];
+  apiPages: LlmsTxtEntry[];
+}
+/**
+ * A page with its URL and full markdown content, used for llms-full.txt generation.
+ *
+ * @public
+ */
+interface PageContent {
+  url: string;
+  content: string;
+}
+/**
+ * Parse a single line from llms.txt format.
+ *
+ * Recognizes the pattern: `- [title](url): description`
+ * The description portion (`: description`) is optional.
+ *
+ * @param line - A single line from an llms.txt file
+ * @returns Parsed entry or null for non-link lines (headers, empty lines, plain text)
+ *
+ * @public
+ */
+declare function parseLlmsTxtLine(line: string): LlmsTxtEntry | null;
+/**
+ * Filter API page entries from global llms.txt content.
+ *
+ * Removes lines whose parsed URL is in the `apiRoutes` set.
+ * Appends pointer lines for per-package llms files when `pointers` is non-empty.
+ *
+ * @param content - Full llms.txt content string
+ * @param apiRoutes - Set of API route paths to remove
+ * @param pointers - Per-package pointer entries to append
+ * @returns Filtered llms.txt content
+ *
+ * @public
+ */
+declare function filterLlmsTxt(content: string, apiRoutes: Set<string>, pointers: PackagePointer[]): string;
+/**
+ * Metadata for a package scope, used to generate structured llms.txt.
+ *
+ * @public
+ */
+interface PackageScopeInfo {
+  /** Display name (e.g., "Kitchen Sink") */
+  name: string;
+  /** npm package name */
+  packageName: string;
+  /** Package version (e.g., "1.0.0") or undefined */
+  version: string | undefined;
+  /** Package description or undefined */
+  description: string | undefined;
+  /** Package-level route prefix (e.g., "/kitchensink") */
+  packageRoute: string;
+  /** URL to the per-package llms-api.txt */
+  llmsApiTxtUrl: string;
+}
+/**
+ * Generate a structured global llms.txt that groups pages by package scope.
+ *
+ * Output format:
+ * ```
+ * # {site title}
+ *
+ * ## Others
+ * - [Blog Post](/blog/post.md)
+ *
+ * ## Packages
+ *
+ * ### {name} {version}
+ * {description}
+ * - [Guide Page](/pkg/guides/guide.md)
+ * - [API Reference](/pkg/llms-api.txt)
+ * ```
+ *
+ * @param content - Original RSPress-generated llms.txt content
+ * @param apiRoutes - Set of API route paths to exclude as individual entries
+ * @param packages - Package scope metadata
+ * @returns Restructured llms.txt content
+ *
+ * @public
+ */
+declare function generateStructuredLlmsTxt(content: string, apiRoutes: Set<string>, packages: PackageScopeInfo[]): string;
+/**
+ * Filter API page content sections from global llms-full.txt.
+ *
+ * Sections are delimited by `---\nurl: {path}\n---` frontmatter blocks.
+ * Removes entire sections whose URL matches a known API route.
+ *
+ * @param content - Full llms-full.txt content string
+ * @param apiRoutes - Set of API route paths to remove
+ * @returns Filtered llms-full.txt content
+ *
+ * @public
+ */
+declare function filterLlmsFullTxt(content: string, apiRoutes: Set<string>): string;
+/**
+ * Generate a per-package llms.txt index.
+ *
+ * Output format:
+ * ```
+ * # {name}
+ *
+ * ## Guides
+ *
+ * - [Guide Title](/path): Description
+ *
+ * ## API Reference
+ *
+ * - [ApiItem](/path): Description
+ * ```
+ *
+ * Sections with no entries are omitted.
+ *
+ * @param input - Package name, guide pages, and API pages
+ * @returns Generated llms.txt content
+ *
+ * @public
+ */
+declare function generatePackageLlmsTxt(input: PackageLlmsTxtInput): string;
+/**
+ * Concatenate page contents with frontmatter delimiters.
+ *
+ * Used for llms-full.txt, llms-docs.txt, and llms-api.txt generation
+ * (pass different page sets for each).
+ *
+ * Output format:
+ * ```
+ * ---
+ * url: /path/to/page
+ * ---
+ *
+ * Content here...
+ *
+ *
+ * ---
+ * url: /path/to/next
+ * ---
+ *
+ * More content...
+ * ```
+ *
+ * @param pages - Array of page URLs and their markdown content
+ * @returns Concatenated content with frontmatter delimiters
+ *
+ * @public
+ */
+declare function generatePackageLlmsFullTxt(pages: PageContent[]): string;
+//#endregion
+//#region src/Markdown.d.ts
+/**
+ * Render one block to flow nodes.
+ *
+ * @public
+ */
+declare function markdownBlockTree(block: Block): ReadonlyArray<FlowContent>;
+/**
+ * Render a page's body to flow nodes — the pre-serialization form of
+ * {@link renderMarkdownResult}.
+ *
+ * @public
+ */
+declare function markdownTree(page: Page): ReadonlyArray<FlowContent>;
+/**
+ * Render a page's body to a markdown string. No frontmatter: that is the
+ * adapter's, built from the page facts.
+ *
+ * @remarks
+ * A stringify failure on a tree this module built itself is surfaced rather
+ * than thrown, because the prose inside a block arrived from a builder and
+ * may carry any node the kit admits; the kit's own error names what it could
+ * not serialize.
+ *
+ * @public
+ */
+declare function renderMarkdownResult(page: Page): Result.Result<string, MarkdownStringifyError>;
+/**
+ * The Effect form of {@link renderMarkdownResult}.
+ *
+ * @public
+ */
+declare const renderMarkdown: (page: Page) => Effect.Effect<string, MarkdownStringifyError>;
+//#endregion
+//#region src/Scope.d.ts
+/**
+ * API scope naming — the helpers that turn a package name and a base route
+ * into the identifiers every adapter must agree on.
+ *
+ * @remarks
+ * These sit beside the navigation tree rather than in an adapter because the
+ * scope string is load-bearing across frameworks: it keys Twoslash cache
+ * generations and names the per-package llms files. Two adapters deriving it
+ * differently would silently miss each other's caches. The multiVersion /
+ * i18n output-directory layout is NOT here — that is a framework's product
+ * policy and stays adapter-side.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Extract the unscoped name from a possibly scoped package name:
+ * `@scope/pkg` becomes `pkg`, `pkg` stays `pkg`.
+ *
+ * @public
+ */
+declare function unscopedName(packageName: string): string;
+/**
+ * Normalize a base route: ensure a leading slash, strip a trailing slash,
+ * and keep the root as `/`.
+ *
+ * @public
+ */
+declare function normalizeBaseRoute(route: string): string;
+/**
+ * The API scope key derived from a base route: its first path segment,
+ * falling back to the package name so a single-API site mounted at `/`
+ * still gets a non-empty scope.
+ *
+ * @remarks
+ * Load-bearing and previously duplicated. Config resolution registers each
+ * API's Twoslash environment under this key and the build program looks it
+ * up by the same key; if two derivations disagree, every lookup misses and
+ * per-scope type-checking degrades to build-wide with no error and nothing
+ * visibly wrong in the output. One definition matters more than the
+ * duplication was costing.
+ *
+ * @public
+ */
+declare function apiScopeOf(baseRoute: string, packageName: string): string;
+//#endregion
+//#region src/TwoslashDirectives.d.ts
+/**
+ * Twoslash directive detection — the regexes that decide which lines of a
+ * code block are notation rather than code.
+ *
+ * @remarks
+ * These mirror the upstream Twoslash source
+ * (`twoslashes/twoslash`, `packages/twoslash/src/regexp.ts`). All patterns
+ * allow an optional space after `//`, so both `// @noErrors` and `//@noErrors`
+ * are recognized, as Twoslash itself does. They live in the IR package
+ * because the display/source split depends on them and both adapters must
+ * strip the same lines.
+ *
+ * @packageDocumentation
+ */
+/**
+ * The four cut directive forms.
+ *
+ * @public
+ */
+type CutDirective = "cut-before" | "cut-after" | "cut-start" | "cut-end";
+/**
+ * Test whether a trimmed line is any Twoslash directive — a config flag or
+ * value, a filename marker, an annotation marker or a cut directive.
+ *
+ * @param trimmedLine - The line with leading and trailing whitespace removed
+ * @returns `true` if the line is a Twoslash directive
+ * @public
+ */
+declare function isTwoslashDirective(trimmedLine: string): boolean;
+/**
+ * Classify a cut directive line.
+ *
+ * @param trimmedLine - The line with leading and trailing whitespace removed
+ * @returns The cut form, or `null` if the line is not a cut directive
+ * @public
+ */
+declare function classifyCutDirective(trimmedLine: string): CutDirective | null;
+//#endregion
+//#region src/WorkItems.d.ts
+/**
+ * Lower number = higher priority for which page a bare cross-link name
+ * resolves to.
+ *
+ * @public
+ */
+declare function crossLinkKindPriority(kind: string): number;
+/**
+ * The facts a category contributes to work-item preparation: how items are
+ * matched to it and where its pages live.
+ *
+ * @public
+ */
+interface WorkItemCategory extends ApiItems.CategorySpec {
+  /** The category's plural display name. */
+  readonly displayName: string;
+  /** The category's singular name — the second title part. */
+  readonly singularName: string;
+  /** The folder the category's pages live in. */
+  readonly folderName: string;
+}
+/**
+ * One page to build: the item plus every fact the builder needs from the
+ * model that the item alone does not carry.
+ *
+ * @public
+ */
+interface WorkItem<C extends WorkItemCategory = WorkItemCategory> {
+  /** The documented item. */
+  readonly item: ApiItem;
+  /** The category key the item was categorized under. */
+  readonly categoryKey: string;
+  /** The category the item was categorized under. */
+  readonly categoryConfig: C;
+  /** Present when the item is a namespace member documented on its own page. */
+  readonly namespaceMember?: ApiItems.NamespaceMember;
+  /** Entry points this item is available from. */
+  readonly availableFrom?: string[];
+  /**
+   * Unexported base declaration referenced by this class's extends clause
+   * (the `Foo_base` variable TypeScript emits for `Schema.Class`-style
+   * patterns). Rendered inline on the class page instead of its own page.
+   */
+  readonly syntheticBase?: ApiItem;
+  /**
+   * Anchor id per member, keyed by the member's canonical reference.
+   *
+   * @remarks
+   * Computed here rather than in the page builder so the `#fragment` in the
+   * cross-link route map and the id the page emits come from ONE computation
+   * and cannot drift. Present for classes and interfaces.
+   */
+  readonly memberAnchors?: ReadonlyMap<string, string>;
+}
+/**
+ * The cross-link maps: display name to route, and display name to item kind
+ * (used only to arbitrate which kind owns a bare name).
+ *
+ * @public
+ */
+interface CrossLinkData {
+  /** Display name (or `Class.member` key) to route path. */
+  readonly routes: Map<string, string>;
+  /** Display name to API item kind. */
+  readonly kinds: Map<string, string>;
+}
+/**
+ * The input to {@link prepareWorkItems}.
+ *
+ * @public
+ */
+interface PrepareWorkItemsInput<C extends WorkItemCategory = WorkItemCategory> {
+  /** The loaded API model. */
+  readonly apiPackage: ApiPackage;
+  /** The categories, in the order their groups are listed. */
+  readonly categories: Readonly<Record<string, C>>;
+  /** The API's base route. */
+  readonly baseRoute: string;
+}
+/**
+ * The result of {@link prepareWorkItems}.
+ *
+ * @remarks
+ * `uncategorized` and `collisions` are returned rather than reported: the
+ * RSPress adapter emits an `ItemSkipped` event per uncategorized item and
+ * throws `Routes.RouteCollisionError` on any collision, and a second adapter
+ * decides for itself. A caller that ignores `collisions` will write two
+ * distinct items to one route, so check it.
+ *
+ * @public
+ */
+interface PrepareWorkItemsResult<C extends WorkItemCategory = WorkItemCategory> {
+  /** Every page to build, top-level items first then namespace members. */
+  readonly workItems: WorkItem<C>[];
+  /** The cross-link maps both prose and code linkers consume. */
+  readonly crossLinkData: CrossLinkData;
+  /** Items no category matched; they get no page. */
+  readonly uncategorized: ReadonlyArray<ApiItem>;
+  /** Distinct items that would share one output route. */
+  readonly collisions: ReadonlyArray<Routes.RouteCollision>;
+}
+/**
+ * Prepare the flat list of work items to build and the cross-link maps.
+ *
+ * @remarks
+ * Resolves entry points into deduplicated items, detects synthetic base
+ * declarations (excluded from categorization, collision detection and work
+ * items — the owner class page renders them inline), categorizes, detects
+ * route collisions on the lowercased `folder/name` route, builds the route
+ * map with bare names owned by the highest-priority kind and member routes
+ * from the model's anchors, adds namespace member routes (qualified always,
+ * unqualified PascalCase when unambiguous), routes synthetic base names to
+ * the owner's `#base-class` anchor, and flattens everything into work items.
+ *
+ * @public
+ */
+declare function prepareWorkItems<C extends WorkItemCategory>(input: PrepareWorkItemsInput<C>): PrepareWorkItemsResult<C>;
+//#endregion
+export { AvailableFrom, BaseClass, Block, type BlockKind, type BuildIndexPageInput, type BuildNavInput, type BuildPageInput, CodeText, type CrossLinkData, type CutDirective, EnumMemberRow, EnumMemberTable, Example, ExampleFormatError, ExampleGroup, type HeadTag, INDEX_PAGE_TITLE, IndexPage, Inline, type LlmsTxtEntry, Member, MemberGroup, MemberIndex, MemberIndexEntry, MemberRole, NAV_INDEX_LABEL, NO_DESCRIPTION, type NamespaceMemberFacts, NavCategory, NavEntry, NavGroup, NavPage, NavTree, type PackageLlmsTxtInput, type PackagePointer, type PackageScopeInfo, Page, type PageContent, PageKind, ParameterRow, ParameterTable, type PrepareWorkItemsInput, type PrepareWorkItemsResult, type PreparedExample, Prose, ProseBlock, ProseRole, type RawExample, ReleaseTag, SeeAlso, Signature, SourceLink, Title, type WorkItem, type WorkItemCategory, addLogicalBlankLines, apiScopeOf, buildExample, buildIndexPage, buildNav, buildPage, classifyCutDirective, codeText, crossLinkKindPriority, filterLlmsFullTxt, filterLlmsTxt, formatExampleCode, generatePackageLlmsFullTxt, generatePackageLlmsTxt, generateStructuredLlmsTxt, isPageKind, isTwoslashDirective, markdownBlockTree, markdownTree, normalizeBaseRoute, parseLlmsTxtLine, prepareExampleCode, prepareWorkItems, prependHiddenImports, renderMarkdown, renderMarkdownResult, sortNavPages, stripTwoslashDirectives, unscopedName };
+//# sourceMappingURL=index.d.ts.map