@cssdoc/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Danny Wahl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,100 @@
+# @cssdoc/core
+
+TSDoc, for CSS. A small, framework-agnostic documentation extractor: parse a doc-comment grammar plus
+the CSS AST into a serializable model, then build whatever emitter you like on top (markdown, JSON, a
+component gallery) — the way `typedoc-plugin-markdown` builds on TypeDoc's reflections.
+
+There's no modern, maintained "TypeDoc for plain CSS" (CSSdoc is abandoned, KSS-node is dated, SassDoc
+is Sass-only). This is the missing core: it reads structured comments and derives the machine facts from
+the actual selectors, so the docs can't drift from the shipping CSS.
+
+## Install
+
+```sh
+npm i -D @cssdoc/core
+```
+
+## Usage
+
+```ts
+import { parseCssDocs, toJson } from "@cssdoc/core";
+import { readFileSync } from "node:fs";
+
+const model = parseCssDocs(readFileSync("dist/components.css", "utf8"));
+writeFileSync("css-docs.json", toJson(model));
+```
+
+`parseCssDocs(css)` returns one `CssDocEntry` per record. It is **AST-first** — modifiers, sub-element
+parts, consumed and declared custom properties, and deprecated-alias links are extracted from the
+selectors, so they never drift. Authored doc comments supply only prose (summaries, descriptions) and
+delimit one component from the next.
+
+## The doc-comment grammar
+
+A `/** … */` block above a component's rules. Records are delimited by `@component`/`@name`. The tag
+vocabulary adopts the Custom Elements Manifest names (`@cssproperty`, `@csspart`, `@cssstate`) where
+they exist, so it's standards-aligned:
+
+```css
+/**
+ * @component button
+ * @summary An accessible action control.
+ * @modifier -color-secondary — A lower-emphasis action.
+ * @part .icon — A leading glyph.
+ * @cssproperty --ring <color> — The focus-ring colour.
+ * @deprecated Use the button utility instead.
+ * @demo self:button
+ */
+.button {
+  /* … */
+}
+.button.-color-secondary {
+  /* … */
+}
+```
+
+| Tag                                        | Meaning                                                                     |
+| ------------------------------------------ | --------------------------------------------------------------------------- |
+| `@component` / `@name <id>`                | Names the record (required; marks a boundary).                              |
+| `@class <selector>`                        | An explicit base class (otherwise inferred from the first bare-class rule). |
+| `@summary <text>`                          | One-line intro.                                                             |
+| `@modifier -<x> — <desc>`                  | Prose for a modifier (the list itself is AST-derived).                      |
+| `@part` / `@csspart .<x> — <desc>`         | Prose for a sub-element part.                                               |
+| `@cssproperty --<x> [<syntax>] — <desc>`   | A declared custom property.                                                 |
+| `@cssstate <x> — <desc>`                   | A component state.                                                          |
+| `@example`, `@deprecated`, `@demo`, `@see` | As in TSDoc.                                                                |
+
+Unknown tags are ignored, so the grammar degrades gracefully.
+
+## Model
+
+`parseCssDocs` returns `CssDocEntry[]`:
+
+```ts
+interface CssDocEntry {
+  name: string;
+  className: string;
+  summary?: string;
+  modifiers: {
+    name: string;
+    prop: string;
+    value?: string;
+    description?: string;
+    deprecated?: { canonical: string };
+  }[];
+  parts: { name: string; description?: string }[];
+  cssPropertiesConsumed: string[];
+  cssPropertiesDeclared: { name: string; syntax?: string; description?: string }[];
+  examples: string[];
+  demo?: string;
+  deprecated?: string;
+  see: string[];
+}
+```
+
+Records default to splitting on `@component`/`@name`; pass `parseCssDocs(css, { isRecordBoundary })` to
+delimit on something else (e.g. a per-component header comment).
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,457 @@
+//#region src/configuration.d.ts
+/**
+ * The syntactic kind of a tag, mirroring TSDoc's Block/Modifier/Inline split, plus cssdoc's own
+ * `record` kind for the tags that open a documentation record (`@component`, `@utility`, …).
+ */
+type CssDocSyntaxKind = "record" | "block" | "modifier" | "inline";
+/** Options for constructing a {@link CssDocTagDefinition}. */
+interface CssDocTagDefinitionOptions {
+  /** The tag name, with or without a leading `@` (e.g. `@modifier` or `modifier`). */
+  tagName: string;
+  /** The tag's syntactic kind. */
+  syntaxKind: CssDocSyntaxKind;
+  /** Whether the tag may appear more than once in a comment (defaults to `false`). */
+  allowMultiple?: boolean;
+  /** For `record` tags, the {@link CssRecordKind} the tag selects. */
+  recordKind?: CssRecordKind;
+  /** The canonical tag (without `@`) this tag is an alias of, e.g. `@csspart` aliases `part`. */
+  aliasFor?: string;
+}
+/** One tag in the vocabulary: its name, kind, and how it may be used. */
+declare class CssDocTagDefinition {
+  /** The normalized tag name, always with a leading `@` (e.g. `@modifier`). */
+  readonly tagName: string;
+  /** The tag name without its leading `@` (e.g. `modifier`). */
+  readonly tagNameWithoutAt: string;
+  readonly syntaxKind: CssDocSyntaxKind;
+  readonly allowMultiple: boolean;
+  readonly recordKind?: CssRecordKind;
+  /** The canonical tag name (without `@`) this aliases, if any; otherwise its own name. */
+  readonly aliasFor?: string;
+  constructor(options: CssDocTagDefinitionOptions);
+  /** The tag this definition resolves to when handled — its alias target, or itself. */
+  get canonicalName(): string;
+}
+/**
+ * A parse configuration: the set of tag definitions plus which are supported. Construct one to get the
+ * full standard vocabulary, then add custom tags or disable standard ones.
+ *
+ * @example
+ * ```ts
+ * import { CssDocConfiguration, CssDocTagDefinition, parseCssDocs } from "@cssdoc/core";
+ *
+ * const config = new CssDocConfiguration();
+ * config.addTagDefinition(new CssDocTagDefinition({ tagName: "@token", syntaxKind: "block" }), true);
+ * const model = parseCssDocs(css, { configuration: config });
+ * ```
+ */
+declare class CssDocConfiguration {
+  private readonly _tagDefinitions;
+  private readonly _byName;
+  private readonly _supported;
+  constructor();
+  /** Every registered tag definition, in registration order. */
+  get tagDefinitions(): readonly CssDocTagDefinition[];
+  /** Only the tag definitions that are currently supported. */
+  get supportedTagDefinitions(): readonly CssDocTagDefinition[];
+  /**
+   * Register a tag definition. Re-registering a tag name replaces the earlier definition.
+   *
+   * @param definition - The tag to add.
+   * @param supported - Whether it is supported (defaults to `true`).
+   */
+  addTagDefinition(definition: CssDocTagDefinition, supported?: boolean): void;
+  /** Register several tag definitions. */
+  addTagDefinitions(definitions: readonly CssDocTagDefinition[], supported?: boolean): void;
+  /** Look up a tag definition by name (with or without a leading `@`). */
+  tryGetTagDefinition(tagName: string): CssDocTagDefinition | undefined;
+  /** Whether a tag definition is supported. */
+  isTagSupported(definition: CssDocTagDefinition): boolean;
+  /** Enable or disable support for a tag. */
+  setSupportForTag(definition: CssDocTagDefinition, supported: boolean): void;
+  /** Enable or disable support for several tags. */
+  setSupportForTags(definitions: readonly CssDocTagDefinition[], supported: boolean): void;
+  /** Disable support for every standard tag (custom tags added later remain supported). */
+  setNoStandardTags(): void;
+  /** The names (without `@`) of every standard tag. */
+  static readonly standardTagNames: readonly string[];
+  /** A fresh set of the standard tag definitions (new instances on each call). */
+  static standardTags(): CssDocTagDefinition[];
+}
+//#endregion
+//#region src/model.d.ts
+/**
+ * The serializable CSS-documentation model — the output-agnostic IR produced by {@link parseCssDocs}.
+ * Emitters (markdown, JSON, …) consume this; it carries no assumptions about any particular project,
+ * class prefix, or output format.
+ *
+ * The model documents the modern CSSOM surface a stylesheet exposes: modifiers and parts, registered
+ * custom properties (`@property`), custom functions (`@function`), animations (`@keyframes`), cascade
+ * layers (`@layer`), conditional-support blocks (`@container`/`@supports`/`@media`), states, and slots.
+ * Facts that can be derived from the CSS AST are derived (so they can't drift); doc-comment tags supply
+ * the prose.
+ *
+ * @module
+ */
+/** A `-<prop>-<value>` (or boolean `-<flag>`) modifier on a component's base class. */
+interface CssModifier {
+  /** The modifier class without the leading dot, e.g. `-color-secondary` or `-condensed`. */
+  name: string;
+  /** The property segment, e.g. `color` (the text after the first `-`, up to the next `-`). */
+  prop: string;
+  /** The value segment, e.g. `secondary`; absent for boolean modifiers. */
+  value?: string;
+  /** Prose from a `@modifier` doc tag, when authored. */
+  description?: string;
+  /**
+   * Set when the modifier is deprecated. `canonical` (from an AST alias marker) is the modifier class
+   * to use instead; `note` (from an authored inline deprecation tag on the `@modifier` line) is
+   * free-text replacement guidance for cases where the replacement isn't itself a modifier.
+   */
+  deprecated?: {
+    canonical?: string;
+    note?: string;
+  };
+}
+/** A sub-element ("part") of a component — a scoped child class like `.item` or `.tip`. */
+interface CssPart {
+  /** The part class without the leading dot, e.g. `item`. */
+  name: string;
+  /** Prose from a `@part` / `@csspart` doc tag, when authored. */
+  description?: string;
+}
+/** A component state — a `:state()` / state-class the component reacts to (`@cssstate`). */
+interface CssState {
+  /** The state name, e.g. `open` or `selected`. */
+  name: string;
+  /** Prose from a `@cssstate` doc tag, when authored. */
+  description?: string;
+}
+/** A named slot a component shell exposes (`@slot`, Custom Elements Manifest). */
+interface CssSlot {
+  /** The slot name (empty string for the default slot). */
+  name: string;
+  /** Prose from a `@slot` doc tag, when authored. */
+  description?: string;
+}
+/** A custom property the component declares (`@property`) or documents (`@cssproperty`). */
+interface CssPropertyDeclared {
+  /** The custom-property name, e.g. `--value`. */
+  name: string;
+  /** The `@property` `syntax` descriptor, e.g. `<number>`, when known. */
+  syntax?: string;
+  /** The `@property` `inherits` flag, when declared. */
+  inherits?: boolean;
+  /** The default value (`@property` `initial-value`, or an authored `@defaultValue`), when known. */
+  defaultValue?: string;
+  /** Prose from a `@cssproperty` doc tag, when authored. */
+  description?: string;
+}
+/** A CSS custom function (`@function --name`) the stylesheet defines. */
+interface CssFunction {
+  /** The function name, e.g. `--negate`. */
+  name: string;
+  /** The declared parameters, e.g. `["--value"]`, when derivable from the `@function` at-rule. */
+  parameters: string[];
+  /** The `result` descriptor/type, when declared. */
+  result?: string;
+  /** Prose from a `@function` doc tag, when authored. */
+  description?: string;
+}
+/** An animation the component exposes (`@keyframes` at-rule / `@animation` doc tag). */
+interface CssAnimation {
+  /** The animation (keyframes) name. */
+  name: string;
+  /** Prose from an `@animation`/`@keyframes` doc tag, when authored. */
+  description?: string;
+}
+/** A cascade layer the stylesheet participates in (`@layer`). */
+interface CssLayer {
+  /** The layer name, possibly dotted (e.g. `theme.dark`). */
+  name: string;
+  /** Prose from a `@layer` doc tag, when authored. */
+  description?: string;
+}
+/** A conditional-support block the component's rules sit under. */
+interface CssCondition {
+  /** Which at-rule expressed the condition. */
+  type: "container" | "supports" | "media";
+  /** The condition text, e.g. `(min-width: 40rem)` or `(display: grid)`. */
+  query: string;
+  /** A container name, for `@container` blocks that target a named container. */
+  containerName?: string;
+  /** Prose from a `@container`/`@supports`/`@media`/`@responsive` doc tag, when authored. */
+  description?: string;
+}
+/**
+ * What kind of CSS surface a record documents. `component` is a namespaced component class with
+ * `-modifier`s and parts; `utility` a single-purpose class family; `rule` bare-element/reset styling;
+ * `declaration` a custom-property / `@property` registration layer. The record-opening tag chooses it
+ * (`@component`/`@utility`/`@rule`/`@declaration`); `@name` is an alias for `component`.
+ */
+type CssRecordKind = "component" | "utility" | "rule" | "declaration";
+/**
+ * A release stage from a modifier (flag) tag — `@alpha`, `@beta`, `@experimental`, `@internal`, or
+ * `@public` — mirroring TSDoc's release-tag semantics.
+ */
+type CssReleaseStage = "alpha" | "beta" | "experimental" | "internal" | "public";
+/**
+ * A node in an authored HTML-structure tree (`@structure`): a selector for the element and its
+ * children. Emitters render it as an indented tree and, via {@link toMermaid}, as a diagram.
+ */
+interface StructureNode {
+  /** The node's selector/label, e.g. `.tabs` or `.tab.-selected` or `button`. */
+  selector: string;
+  /** Child nodes (one indentation level deeper). */
+  children: StructureNode[];
+}
+/** One documented CSS record: its base class plus everything derived from the CSS + doc comments. */
+interface CssDocEntry {
+  /** The record name from `@component`/`@utility`/`@rule`/`@declaration`/`@name`, e.g. `button`. */
+  name: string;
+  /** Which kind of CSS surface this documents (defaults to `component`). */
+  kind: CssRecordKind;
+  /** The base class selector, e.g. `.button` (inferred from the first bare-class rule). */
+  className: string;
+  /** One-line summary from `@summary`. */
+  summary?: string;
+  /** Extended prose from `@remarks`. */
+  remarks?: string;
+  /** Internal-only prose from `@privateRemarks` (emitters may choose to omit it from public output). */
+  privateRemarks?: string;
+  /** The release stage from a modifier flag tag (`@alpha`/`@beta`/`@experimental`/`@internal`/`@public`). */
+  releaseStage?: CssReleaseStage;
+  /** Version introduced, from `@since`. */
+  since?: string;
+  /** A documentation group/category, from `@group`/`@category`. */
+  group?: string;
+  /** Accessibility guidance, from `@a11y`/`@accessibility`. */
+  accessibility?: string;
+  /** AST-extracted modifiers, annotated with `@modifier` prose where authored. */
+  modifiers: CssModifier[];
+  /** AST-extracted sub-element parts, annotated with `@part`/`@csspart` prose where authored. */
+  parts: CssPart[];
+  /** States the component reacts to, from `@cssstate`. */
+  states: CssState[];
+  /** Named slots the component shell exposes, from `@slot`. */
+  slots: CssSlot[];
+  /** Every `--*` custom property referenced via `var(...)` inside this component's rules. */
+  cssPropertiesConsumed: string[];
+  /** Custom properties this component declares (`@property`) or documents (`@cssproperty`). */
+  cssPropertiesDeclared: CssPropertyDeclared[];
+  /** CSS custom functions (`@function`) this component defines. */
+  functions: CssFunction[];
+  /** Animations (`@keyframes`) this component exposes. */
+  animations: CssAnimation[];
+  /** Cascade layers (`@layer`) this component participates in. */
+  layers: CssLayer[];
+  /** Conditional-support blocks (`@container`/`@supports`/`@media`) the rules sit under. */
+  conditions: CssCondition[];
+  /** `@example` blocks, verbatim. */
+  examples: string[];
+  /** The authored `@structure` HTML tree (top-level nodes), when present. */
+  structure?: StructureNode[];
+  /** `@demo <spec>` (e.g. `self:button`), when authored. */
+  demo?: string;
+  /** Component-level deprecation replacement text, when authored (the argument to a `@deprecated` tag). */
+  deprecated?: string;
+  /** `@see <ref>` cross-references. */
+  see: string[];
+  /**
+   * Content of registered custom (block) tags, keyed by tag name without its `@`. Populated only for
+   * tags added via configuration; unregistered unknown tags are ignored. Absent when none were found.
+   */
+  customBlocks?: Record<string, string[]>;
+}
+/** Options for {@link parseCssDocs}. */
+interface ParseOptions {
+  /**
+   * How records are delimited. By default a new record begins at any doc comment (`/** … *\/`) that
+   * carries an `@component` or `@name` tag, which is the recommended, framework-agnostic convention.
+   * Supply a custom test to split on something else (e.g. a per-component header comment).
+   */
+  isRecordBoundary?: (commentText: string) => string | undefined;
+  /**
+   * The tag configuration (standard + custom tags, and which are supported). Defaults to a fresh
+   * {@link CssDocConfiguration} with every standard tag enabled — i.e. the full built-in vocabulary.
+   * Supply one (e.g. from `@cssdoc/config`) to register custom tags or disable standard ones.
+   */
+  configuration?: CssDocConfiguration;
+}
+//#endregion
+//#region src/parse.d.ts
+/**
+ * Parse a CSS string into a documentation model. Records are delimited by doc comments carrying a
+ * record tag (`@component`/`@name` by default; override via {@link ParseOptions.isRecordBoundary});
+ * everything from one boundary comment to the next belongs to that record.
+ *
+ * @param css - The CSS source (a generated stylesheet, with authored doc comments).
+ * @param options - {@link ParseOptions}.
+ * @returns One {@link CssDocEntry} per record, in document order.
+ *
+ * @example
+ * ```ts
+ * import { parseCssDocs } from "@cssdoc/core";
+ *
+ * const [badge] = parseCssDocs(badgeCssWithDocComments);
+ * badge.modifiers.map((m) => m.name); // ["-color-danger", "-color-success", …]
+ * ```
+ */
+declare function parseCssDocs(css: string, options?: ParseOptions): CssDocEntry[];
+//#endregion
+//#region src/grammar.d.ts
+/**
+ * The record-opening tags and the {@link CssRecordKind} each selects, as the default boundary map.
+ * A doc comment carrying one of these opens a new record; `@name` is an alias for `@component`. A
+ * {@link CssDocConfiguration} may add more record tags.
+ */
+declare const RECORD_TAGS: Record<string, CssRecordKind>;
+/** A custom property documented by a `@cssproperty` tag. */
+interface DocCssProperty {
+  name: string;
+  syntax?: string;
+  defaultValue?: string;
+  description?: string;
+}
+/** The prose a `@modifier` tag contributes: a description and/or an inline deprecation replacement note. */
+interface DocModifier {
+  description?: string;
+  /** Set when the modifier carries a bare `@deprecated` (no note and no canonical link). */
+  deprecatedFlag?: boolean;
+  /** Free-text replacement guidance from an inline `deprecated` tag on the modifier line. */
+  deprecated?: string;
+  /**
+   * The canonical modifier this one deprecates, from a `{@link -canonical}` in the deprecation note
+   * (e.g. `@deprecated {@link -color-danger}`). Stored without its leading dot, matching the AST-derived
+   * `deprecated.canonical`, so an authored alias and a generated one resolve to the same reference.
+   */
+  deprecatedCanonical?: string;
+}
+/** An authored conditional-support tag (`@container`/`@supports`/`@media`/`@responsive`). */
+interface DocCondition {
+  type: "container" | "supports" | "media";
+  query: string;
+  description?: string;
+}
+/** The structured content extracted from one doc-comment block. */
+interface ParsedDoc {
+  /** `@component`/`@utility`/`@rule`/`@declaration`/`@name` — the record name. Marks a record boundary. */
+  component?: string;
+  /** The record kind chosen by the opening tag (`component` unless `@utility`/`@rule`/`@declaration`). */
+  kind?: CssRecordKind;
+  /** `@class` — an explicit base class selector (otherwise inferred from the CSS). */
+  className?: string;
+  /** `@summary` — one-line intro. */
+  summary?: string;
+  /** `@remarks` — extended prose. */
+  remarks?: string;
+  /** `@privateRemarks` — internal-only prose. */
+  privateRemarks?: string;
+  /** `@since` — version introduced. */
+  since?: string;
+  /** `@group`/`@category` — a documentation group. */
+  group?: string;
+  /** `@a11y`/`@accessibility` — accessibility guidance. */
+  accessibility?: string;
+  /** The release stage from a modifier flag tag (`@alpha`/`@beta`/…). */
+  releaseStage?: CssReleaseStage;
+  /** `@modifier` prose, keyed by the modifier class without its dot (e.g. `-color-secondary`). */
+  modifiers: Map<string, DocModifier>;
+  /** `@part`/`@csspart` descriptions, keyed by the part name without its dot (e.g. `item`). */
+  parts: Map<string, string>;
+  /** `@cssproperty` declarations. */
+  cssProperties: DocCssProperty[];
+  /** `@cssstate` descriptions, keyed by state name. */
+  cssStates: Map<string, string>;
+  /** `@slot` descriptions, keyed by slot name (empty string for the default slot). */
+  slots: Map<string, string>;
+  /** `@function` descriptions, keyed by function name (e.g. `--negate`). */
+  functions: Map<string, string>;
+  /** `@keyframes`/`@animation` descriptions, keyed by animation name. */
+  animations: Map<string, string>;
+  /** `@layer` descriptions, keyed by layer name. */
+  layers: Map<string, string>;
+  /** `@container`/`@supports`/`@media`/`@responsive` authored conditions. */
+  conditions: DocCondition[];
+  /** `@example` blocks. */
+  examples: string[];
+  /** `@structure` — the raw (indented) HTML-tree body, parsed into nodes by {@link parseStructure}. */
+  structure?: StructureNode[];
+  /** The `<replacement>` argument from a `@deprecated` tag. */
+  deprecated?: string;
+  /** `@demo <spec>`. */
+  demo?: string;
+  /** `@see <ref>` entries. */
+  see: string[];
+  /** Content of registered custom (block) tags, keyed by tag name without its `@`. */
+  customBlocks: Map<string, string[]>;
+}
+/** Strip the comment framing (`/**`, `*\/`, and leading ` * `) from a raw block-comment body. */
+declare function stripCommentFraming(raw: string): string;
+/**
+ * Parse a doc-comment's INNER text (already stripped of `/* *\/` framing, or a raw block — both are
+ * handled) into a {@link ParsedDoc}. The `configuration` decides which tags are active and which custom
+ * tags to capture; unknown or unsupported tags are ignored, so the grammar degrades gracefully.
+ *
+ * @param raw - The comment text (with or without `/** … *\/` framing).
+ * @param configuration - The active tag configuration (defaults to the full standard vocabulary).
+ * @returns The structured tags.
+ */
+declare function parseDocComment(raw: string, configuration?: CssDocConfiguration): ParsedDoc;
+/**
+ * Whether a comment's text opens a record — i.e. carries a record tag. Uses the `configuration`'s
+ * record tags when given, else the default {@link RECORD_TAGS}.
+ *
+ * @param commentText - The comment body.
+ * @param configuration - The active configuration (optional).
+ * @returns The record name, or `undefined`.
+ */
+declare function recordNameOf(commentText: string, configuration?: CssDocConfiguration): string | undefined;
+/**
+ * Parse a `@structure` body — an indentation-nested list of element selectors — into a
+ * {@link StructureNode} tree. Indentation depth (any consistent width) sets nesting; blank lines are
+ * ignored.
+ *
+ * @example
+ * ```
+ * .tabs
+ *   .list
+ *     .tab
+ *   .panel
+ * ```
+ */
+declare function parseStructure(raw: string): StructureNode[];
+//#endregion
+//#region src/mermaid.d.ts
+/**
+ * Convert a structure tree to a Mermaid `flowchart` definition. Each node gets a stable id (`n0`, `n1`,
+ * …) in depth-first order; edges connect a parent to each child.
+ *
+ * @param roots - Top-level {@link StructureNode}s (an authored `@structure`).
+ * @param options - `direction` sets the flowchart orientation (default `TD`, top-down).
+ * @returns Mermaid source, or an empty string when there are no nodes.
+ *
+ * @example
+ * ```ts
+ * toMermaid([{ selector: ".tabs", children: [{ selector: ".panel", children: [] }] }]);
+ * // flowchart TD
+ * //   n0[".tabs"]
+ * //   n1[".panel"]
+ * //   n0 --> n1
+ * ```
+ */
+declare function toMermaid(roots: StructureNode[], options?: {
+  direction?: "TD" | "LR";
+}): string;
+//#endregion
+//#region src/index.d.ts
+/**
+ * Serialize a documentation model to pretty JSON (the raw, emitter-agnostic artifact — like TypeDoc's
+ * `--json`).
+ *
+ * @param model - The entries from {@link parseCssDocs}.
+ * @returns A JSON string.
+ */
+declare function toJson(model: CssDocEntry[]): string;
+//#endregion
+export { type CssAnimation, type CssCondition, CssDocConfiguration, type CssDocEntry, type CssDocSyntaxKind, CssDocTagDefinition, type CssDocTagDefinitionOptions, type CssFunction, type CssLayer, type CssModifier, type CssPart, type CssPropertyDeclared, type CssRecordKind, type CssReleaseStage, type CssSlot, type CssState, type DocCondition, type DocCssProperty, type DocModifier, type ParseOptions, type ParsedDoc, RECORD_TAGS, type StructureNode, parseCssDocs, parseDocComment, parseStructure, recordNameOf, stripCommentFraming, toJson, toMermaid };