@cssdoc/core 0.5.3 → 0.6.0

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { A as CssState, B as ModifierMatcher, C as CssPart, D as CssReleaseStage, E as CssRelated, F as DEFAULT_STATE_PSEUDO_CLASSES, I as MODIFIER_PRESETS, L as ModifierConvention, M as ParseOptions, N as StructureNode, O as CssSlot, P as DEFAULT_MODIFIER_CONVENTION, R as ModifierConventionInput, S as CssParse, T as CssRecordKind, V as resolveModifierConvention, _ as CssCondition, a as DocModifier, b as CssLayer, c as parseDocComment, d as stripCommentFraming, f as CssDocConfiguration, g as CssAnimation, h as CssDocTagDefinitionOptions, i as DocCssProperty, j as CssTokenConsumed, k as CssSource, l as parseStructure, m as CssDocTagDefinition, n as toMermaid, o as ParsedDoc, p as CssDocSyntaxKind, r as DocCondition, s as RECORD_TAGS, t as toJson, u as recordNameOf, v as CssDocEntry, w as CssPropertyDeclared, x as CssModifier, y as CssFunction, z as ModifierHit } from "./lite-DtKEwRkS.mjs";
+import { A as CssSource, B as ModifierHit, C as CssParse, D as CssRelated, E as CssRecordKind, F as DEFAULT_MODIFIER_CONVENTION, H as resolveModifierConvention, I as DEFAULT_STATE_PSEUDO_CLASSES, L as MODIFIER_PRESETS, M as CssTokenConsumed, N as ParseOptions, O as CssReleaseStage, P as StructureNode, R as ModifierConvention, S as CssModifier, T as CssPropertyDeclared, V as ModifierMatcher, _ as CssAnimation, a as DocModifier, b as CssFunction, c as parseDocComment, d as stripCommentFraming, f as CssDocConfiguration, g as InlineCommentMode, h as CssDocTagDefinitionOptions, i as DocCssProperty, j as CssState, k as CssSlot, l as parseStructure, m as CssDocTagDefinition, n as toMermaid, o as ParsedDoc, p as CssDocSyntaxKind, r as DocCondition, s as RECORD_TAGS, t as toJson, u as recordNameOf, v as CssCondition, w as CssPart, x as CssLayer, y as CssDocEntry, z as ModifierConventionInput } from "./lite-DzhifijA.mjs";
 
 //#region src/parse.d.ts
 /**
@@ -20,4 +20,4 @@ import { A as CssState, B as ModifierMatcher, C as CssPart, D as CssReleaseStage
  */
 declare function parseCssDocs(css: string, options?: ParseOptions): CssDocEntry[];
 //#endregion
-export { type CssAnimation, type CssCondition, CssDocConfiguration, type CssDocEntry, type CssDocSyntaxKind, CssDocTagDefinition, type CssDocTagDefinitionOptions, type CssFunction, type CssLayer, type CssModifier, type CssParse, type CssPart, type CssPropertyDeclared, type CssRecordKind, type CssRelated, type CssReleaseStage, type CssSlot, type CssSource, type CssState, type CssTokenConsumed, DEFAULT_MODIFIER_CONVENTION, DEFAULT_STATE_PSEUDO_CLASSES, type DocCondition, type DocCssProperty, type DocModifier, MODIFIER_PRESETS, type ModifierConvention, type ModifierConventionInput, type ModifierHit, ModifierMatcher, type ParseOptions, type ParsedDoc, RECORD_TAGS, type StructureNode, parseCssDocs, parseDocComment, parseStructure, recordNameOf, resolveModifierConvention, stripCommentFraming, toJson, toMermaid };
+export { type CssAnimation, type CssCondition, CssDocConfiguration, type CssDocEntry, type CssDocSyntaxKind, CssDocTagDefinition, type CssDocTagDefinitionOptions, type CssFunction, type CssLayer, type CssModifier, type CssParse, type CssPart, type CssPropertyDeclared, type CssRecordKind, type CssRelated, type CssReleaseStage, type CssSlot, type CssSource, type CssState, type CssTokenConsumed, DEFAULT_MODIFIER_CONVENTION, DEFAULT_STATE_PSEUDO_CLASSES, type DocCondition, type DocCssProperty, type DocModifier, type InlineCommentMode, MODIFIER_PRESETS, type ModifierConvention, type ModifierConventionInput, type ModifierHit, ModifierMatcher, type ParseOptions, type ParsedDoc, RECORD_TAGS, type StructureNode, parseCssDocs, parseDocComment, parseStructure, recordNameOf, resolveModifierConvention, stripCommentFraming, toJson, toMermaid };

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { a as parseStructure, c as CssDocConfiguration, d as DEFAULT_STATE_PSEUDO_CLASSES, f as MODIFIER_PRESETS, i as parseDocComment, l as CssDocTagDefinition, m as resolveModifierConvention, n as toMermaid, o as recordNameOf, p as ModifierMatcher, r as RECORD_TAGS, s as stripCommentFraming, t as toJson, u as DEFAULT_MODIFIER_CONVENTION } from "./lite-HEYG01Eo.mjs";
+import { a as parseStructure, c as CssDocConfiguration, d as DEFAULT_STATE_PSEUDO_CLASSES, f as MODIFIER_PRESETS, i as parseDocComment, l as CssDocTagDefinition, m as resolveModifierConvention, n as toMermaid, o as recordNameOf, p as ModifierMatcher, r as RECORD_TAGS, s as stripCommentFraming, t as toJson, u as DEFAULT_MODIFIER_CONVENTION } from "./lite-CEVmwLGF.mjs";
 import postcss from "postcss";
 //#region src/parse.ts
 /**
@@ -38,12 +38,20 @@ function collectFunction(node, acc) {
 	});
 }
 /** Extract every fact from one record's nodes into `acc`. */
-function collect(nodes, acc, matcher, baseNoDot, prefixNoDot, inScope) {
+function collect(nodes, acc, matcher, baseNoDot, prefixNoDot, inScope, inlineMode) {
 	let pendingCanonical;
+	let pendingDescription;
 	for (const node of nodes) {
 		if (node.type === "comment") {
 			const dep = node.text.match(/@deprecated.*?use\s+(\.[\w-]+|\[[^\]]*\])/u);
 			if (dep) pendingCanonical = matcher.normalizeMember(dep[1]);
+			else if (/(^|\s)@todo\b/u.test(node.text)) {
+				const todo = stripCommentFraming(node.text).replace(/^@todo\b[:\s]*/u, "").trim();
+				if (todo) acc.todos.push(todo);
+			} else if (!/^\s*cssdoc-/u.test(node.text) && inlineMode !== "ignore") {
+				const text = stripCommentFraming(node.text).replace(/\s+/gu, " ").trim();
+				if (text) pendingDescription = text;
+			}
 			continue;
 		}
 		if (node.type === "decl") {
@@ -98,7 +106,7 @@ function collect(nodes, acc, matcher, baseNoDot, prefixNoDot, inScope) {
 				type: "media",
 				query: node.params.trim()
 			});
-			if (node.nodes) collect(node.nodes, acc, matcher, baseNoDot, prefixNoDot, inScope || node.name === "scope");
+			if (node.nodes) collect(node.nodes, acc, matcher, baseNoDot, prefixNoDot, inScope || node.name === "scope", inlineMode);
 			continue;
 		}
 		if (node.type === "rule") {
@@ -112,6 +120,10 @@ function collect(nodes, acc, matcher, baseNoDot, prefixNoDot, inScope) {
 					kind: "pseudo-class"
 				});
 				for (const sp of selector.matchAll(/::part\(\s*([\w-]+)\s*\)/gu)) if (!acc.shadowParts.has(sp[1])) acc.shadowParts.set(sp[1], { name: sp[1] });
+				for (const pe of matcher.pseudoElementsIn(selector)) if (!acc.pseudoElements.has(pe.name)) acc.pseudoElements.set(pe.name, {
+					name: pe.name,
+					description: pendingDescription
+				});
 				const bare = selector.replace(/::?[\w-]+(\([^)]*\))?/gu, "");
 				const mods = matcher.modifiersIn(bare, baseNoDot);
 				const modNames = new Set(mods.map((mod) => mod.name));
@@ -123,10 +135,12 @@ function collect(nodes, acc, matcher, baseNoDot, prefixNoDot, inScope) {
 						...mod.pattern ? { pattern: true } : {}
 					};
 					if (pendingCanonical) entry.deprecated = { canonical: pendingCanonical };
+					if (pendingDescription && !entry.description) entry.description = pendingDescription;
 					acc.modifiers.set(mod.name, entry);
 				}
 				for (const el of matcher.elementsIn(bare, baseNoDot)) {
 					const part = acc.parts.get(el.name) ?? { name: el.name };
+					if (pendingDescription && !part.description) part.description = pendingDescription;
 					for (const m of el.modifiers) {
 						part.modifiers ??= [];
 						if (!part.modifiers.some((x) => x.name === m.name)) part.modifiers.push({
@@ -145,17 +159,33 @@ function collect(nodes, acc, matcher, baseNoDot, prefixNoDot, inScope) {
 					const part = m[1];
 					if (modNames.has(part)) continue;
 					if (prefixNoDot && part.startsWith(prefixNoDot)) continue;
-					if (!acc.parts.has(part)) acc.parts.set(part, { name: part });
+					if (!acc.parts.has(part)) acc.parts.set(part, {
+						name: part,
+						description: pendingDescription
+					});
 				}
 			}
 			for (const child of node.nodes ?? []) if (child.type === "decl") for (const m of child.value.matchAll(VAR_RE)) acc.consumed.add(m[1]);
 			pendingCanonical = void 0;
+			pendingDescription = void 0;
 		}
 	}
 }
 const byName = (a, b) => a.name.localeCompare(b.name);
+/**
+* Combine a member's authored tag prose with an inline `/* … *\/` comment, per the configured
+* {@link InlineCommentMode}. Either side may be absent; when both are present, `append`/`prepend` join
+* them (tag-first / comment-first), `replace` takes the comment, and `ignore` keeps only the tag.
+*/
+function combineDescription(mode, tag, inline) {
+	if (mode === "ignore") return tag;
+	if (!tag) return inline;
+	if (!inline) return tag;
+	if (mode === "replace") return inline;
+	return mode === "prepend" ? `${inline}\n\n${tag}` : `${tag}\n\n${inline}`;
+}
 /** Build one entry from its record name, doc comment, and nodes. */
-function buildEntry(name, doc, nodes, matcher, source) {
+function buildEntry(name, doc, nodes, matcher, inlineMode, source) {
 	let className = doc.className ?? "";
 	if (!className) {
 		const bare = nodes.filter((n) => n.type === "rule").map((n) => n.selector.trim()).filter((sel) => /^\.[a-z][\w-]*$/u.test(sel));
@@ -169,15 +199,17 @@ function buildEntry(name, doc, nodes, matcher, source) {
 		modifiers: /* @__PURE__ */ new Map(),
 		parts: /* @__PURE__ */ new Map(),
 		shadowParts: /* @__PURE__ */ new Map(),
+		pseudoElements: /* @__PURE__ */ new Map(),
 		states: /* @__PURE__ */ new Map(),
 		consumed: /* @__PURE__ */ new Set(),
 		declared: /* @__PURE__ */ new Map(),
 		functions: /* @__PURE__ */ new Map(),
 		animations: /* @__PURE__ */ new Map(),
 		layers: /* @__PURE__ */ new Map(),
-		conditions: []
+		conditions: [],
+		todos: []
 	};
-	collect(nodes, acc, matcher, className.replace(/^\./u, ""), className.endsWith(name) ? className.slice(1, className.length - name.length) : "", false);
+	collect(nodes, acc, matcher, className.replace(/^\./u, ""), className.endsWith(name) ? className.slice(1, className.length - name.length) : "", false, inlineMode);
 	for (const [modName, mdoc] of doc.modifiers) {
 		const existing = acc.modifiers.get(modName);
 		const dep = mdoc.deprecated || mdoc.deprecatedCanonical || mdoc.deprecatedFlag ? {
@@ -185,7 +217,7 @@ function buildEntry(name, doc, nodes, matcher, source) {
 			...mdoc.deprecatedCanonical ? { canonical: mdoc.deprecatedCanonical } : {}
 		} : void 0;
 		if (existing) {
-			if (mdoc.description) existing.description = mdoc.description;
+			existing.description = combineDescription(inlineMode, mdoc.description, existing.description);
 			if (dep) existing.deprecated = {
 				...existing.deprecated,
 				...dep
@@ -204,7 +236,7 @@ function buildEntry(name, doc, nodes, matcher, source) {
 	}
 	for (const [part, description] of doc.parts) {
 		const existing = acc.parts.get(part);
-		if (existing) existing.description = description || existing.description;
+		if (existing) existing.description = combineDescription(inlineMode, description || void 0, existing.description);
 		else acc.parts.set(part, {
 			name: part,
 			description
@@ -218,6 +250,14 @@ function buildEntry(name, doc, nodes, matcher, source) {
 			description: description || void 0
 		});
 	}
+	for (const [pseudo, description] of doc.pseudoElements) {
+		const existing = acc.pseudoElements.get(pseudo);
+		if (existing) existing.description = combineDescription(inlineMode, description || void 0, existing.description);
+		else acc.pseudoElements.set(pseudo, {
+			name: pseudo,
+			description: description || void 0
+		});
+	}
 	for (const [rawState, description] of doc.cssStates) {
 		const isPseudo = rawState.startsWith(":");
 		const state = isPseudo ? rawState.slice(1) : rawState;
@@ -284,6 +324,17 @@ function buildEntry(name, doc, nodes, matcher, source) {
 			description: description || void 0
 		});
 	}
+	if (doc.wrappers.size && doc.structure?.length) {
+		const applyWrappers = (nodes) => {
+			for (const node of nodes) {
+				const cls = node.selector.match(/\.([\w-]+)/u)?.[1];
+				const description = cls ? doc.wrappers.get(cls) : void 0;
+				if (description) node.description = description;
+				applyWrappers(node.children);
+			}
+		};
+		applyWrappers(doc.structure);
+	}
 	return {
 		name,
 		kind: doc.kind ?? "component",
@@ -301,11 +352,13 @@ function buildEntry(name, doc, nodes, matcher, source) {
 			modifiers: [...p.modifiers].sort(byName)
 		} : p),
 		shadowParts: [...acc.shadowParts.values()].sort(byName),
+		pseudoElements: [...acc.pseudoElements.values()].sort(byName),
 		states: [...acc.states.values()].sort(byName),
 		slots: [...doc.slots].map(([slotName, description]) => ({
 			name: slotName,
 			description: description || void 0
 		})).sort(byName),
+		todos: [...doc.todos, ...acc.todos],
 		cssPropertiesConsumed: [...consumedTokens.values()].sort(byName),
 		cssPropertiesDeclared: [...acc.declared.values()].sort(byName),
 		functions: [...acc.functions.values()].sort(byName),
@@ -383,7 +436,7 @@ function parseCssDocs(css, options = {}) {
 		}
 		if (current) current.nodes.push(node);
 	}
-	return records.map((r) => buildEntry(r.name, r.doc, r.nodes, matcher, r.source));
+	return records.map((r) => buildEntry(r.name, r.doc, r.nodes, matcher, configuration.inlineComments, r.source));
 }
 //#endregion
 export { CssDocConfiguration, CssDocTagDefinition, DEFAULT_MODIFIER_CONVENTION, DEFAULT_STATE_PSEUDO_CLASSES, MODIFIER_PRESETS, ModifierMatcher, RECORD_TAGS, parseCssDocs, parseDocComment, parseStructure, recordNameOf, resolveModifierConvention, stripCommentFraming, toJson, toMermaid };

package/dist/{lite-HEYG01Eo.mjs → lite-CEVmwLGF.mjs}

@@ -22,6 +22,23 @@ const DEFAULT_STATE_PSEUDO_CLASSES = [
 	"in-range",
 	"out-of-range"
 ];
+/**
+* The native pseudo-elements cssdoc documents by default when a component styles them. A curated set of
+* the standard ones — vendor/experimental pseudo-elements (`::-webkit-*`) are left out so incidental
+* rules don't become documented API. `::part()`/`::slotted()` are handled separately (shadow parts).
+*/
+const DEFAULT_PSEUDO_ELEMENTS = [
+	"before",
+	"after",
+	"marker",
+	"placeholder",
+	"selection",
+	"backdrop",
+	"first-line",
+	"first-letter",
+	"file-selector-button",
+	"details-content"
+];
 /** The built-in convention presets. Other schemes use the custom object (see the docs). */
 const MODIFIER_PRESETS = {
 	/** BEM / SUIT — `.button--primary`, with `.button__element` sub-elements. The default. */
@@ -65,6 +82,7 @@ function resolveModifierConvention(input) {
 		...base.elementSeparator !== void 0 ? { elementSeparator: base.elementSeparator } : {},
 		...base.statePrefixes !== void 0 ? { statePrefixes: base.statePrefixes } : {},
 		statePseudoClasses: base.statePseudoClasses ?? [...DEFAULT_STATE_PSEUDO_CLASSES],
+		pseudoElements: base.pseudoElements ?? [...DEFAULT_PSEUDO_ELEMENTS],
 		propValue: base.propValue ?? false,
 		propValueSeparator: base.propValueSeparator ?? "-"
 	};
@@ -92,6 +110,8 @@ var ModifierMatcher = class {
 	statePrefixes;
 	/** Native pseudo-classes (no `:`) recognized as states. */
 	statePseudoClasses;
+	/** Native pseudo-elements (no `::`) recognized as documented pseudo-elements. */
+	pseudoElements;
 	constructor(convention) {
 		this.convention = convention;
 		const longestFirst = (value) => (Array.isArray(value) ? value : [value]).slice().sort((a, b) => b.length - a.length);
@@ -101,6 +121,7 @@ var ModifierMatcher = class {
 		this.elementSepAlt = this.elementSeparators.length ? `(?:${this.elementSeparators.map(escapeRe).join("|")})` : "";
 		this.statePrefixes = (convention.statePrefixes ?? []).filter((p) => p !== "").slice().sort((a, b) => b.length - a.length);
 		this.statePseudoClasses = new Set(convention.statePseudoClasses ?? []);
+		this.pseudoElements = new Set(convention.pseudoElements ?? []);
 	}
 	/** Does a class name (no leading dot) start with one of the convention's state prefixes? */
 	isStateClass(name) {
@@ -268,6 +289,24 @@ var ModifierMatcher = class {
 		}
 		return out;
 	}
+	/**
+	* Every native pseudo-element on the selector recognized for documentation — a `::name` whose `name`
+	* is in the convention's {@link ModifierConvention.pseudoElements} (e.g. `.alert::before` → `before`).
+	* `::part()`/`::slotted()` and pseudo-elements not in the set are ignored.
+	*/
+	pseudoElementsIn(selector) {
+		if (this.pseudoElements.size === 0) return [];
+		const seen = /* @__PURE__ */ new Set();
+		const out = [];
+		for (const m of selector.matchAll(/::([\w-]+)/gu)) {
+			const name = m[1];
+			if (this.pseudoElements.has(name) && !seen.has(name)) {
+				seen.add(name);
+				out.push({ name });
+			}
+		}
+		return out;
+	}
 	/** Derive `prop`/`value` for a modifier `name` (as returned by {@link modifiersIn} or authored). */
 	analyze(name) {
 		if (name.includes("*")) {
@@ -402,24 +441,12 @@ var CssDocTagDefinition = class {
 function def(options) {
 	return new CssDocTagDefinition(options);
 }
-/**
-* 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 });
-* ```
-*/
 var CssDocConfiguration = class CssDocConfiguration {
 	_tagDefinitions = [];
 	_byName = /* @__PURE__ */ new Map();
 	_supported = /* @__PURE__ */ new Set();
 	_modifierConvention = DEFAULT_MODIFIER_CONVENTION;
+	_inlineComments = "append";
 	constructor() {
 		this.addTagDefinitions(CssDocConfiguration.standardTags(), true);
 	}
@@ -431,6 +458,14 @@ var CssDocConfiguration = class CssDocConfiguration {
 	setModifierConvention(input) {
 		this._modifierConvention = resolveModifierConvention(input);
 	}
+	/** How inline `/* … *\/` comments combine with tag prose (defaults to `append`). */
+	get inlineComments() {
+		return this._inlineComments;
+	}
+	/** Set the inline-comment combine mode. */
+	setInlineComments(mode) {
+		this._inlineComments = mode;
+	}
 	/** Every registered tag definition, in registration order. */
 	get tagDefinitions() {
 		return this._tagDefinitions;
@@ -561,6 +596,9 @@ function parseDocComment(raw, configuration = new CssDocConfiguration(), parse)
 		parts: /* @__PURE__ */ new Map(),
 		tokens: /* @__PURE__ */ new Map(),
 		cssParts: /* @__PURE__ */ new Map(),
+		pseudoElements: /* @__PURE__ */ new Map(),
+		wrappers: /* @__PURE__ */ new Map(),
+		todos: [],
 		cssProperties: [],
 		cssStates: /* @__PURE__ */ new Map(),
 		slots: /* @__PURE__ */ new Map(),
@@ -613,6 +651,11 @@ function applyBlockTag(doc, canonical, tagName, rest, parse) {
 		case "privateRemarks":
 			doc.privateRemarks = rest.trim();
 			break;
+		case "todo": {
+			const todo = rest.trim();
+			if (todo) doc.todos.push(todo);
+			break;
+		}
 		case "since":
 			doc.since = rest.trim();
 			break;
@@ -648,6 +691,16 @@ function applyBlockTag(doc, canonical, tagName, rest, parse) {
 			doc.cssParts.set(head.replace(/^\./u, ""), description ?? "");
 			break;
 		}
+		case "pseudo": {
+			const { head, description } = splitDesc(rest);
+			doc.pseudoElements.set(head.replace(/^::/u, ""), description ?? "");
+			break;
+		}
+		case "wrapper": {
+			const { head, description } = splitDesc(rest);
+			doc.wrappers.set(head.replace(/^\./u, ""), description ?? "");
+			break;
+		}
 		case "cssproperty": {
 			const propMatch = rest.match(/^(--[\w-]+)\s*(<[^>]+>)?\s*(?:(?:—|-{1,2})\s*(.*))?$/u);
 			if (propMatch) doc.cssProperties.push({
@@ -700,7 +753,7 @@ function applyBlockTag(doc, canonical, tagName, rest, parse) {
 			break;
 		}
 		case "example":
-			doc.examples.push(rest);
+			doc.examples.push(rest.replace(/\\`/gu, "`"));
 			break;
 		case "deprecated":
 			doc.deprecated = rest;
@@ -828,6 +881,12 @@ const EDGE = {
 	many: "-->|0..n|",
 	"one-or-more": "-->|1..n|"
 };
+/** The ER range token for a cardinality — used on the root's label, which has no incoming edge. */
+const CARDINALITY_TOKEN = {
+	optional: "0..1",
+	many: "0..n",
+	"one-or-more": "1..n"
+};
 /** Wrap a node's label in the shape mermaid draws for its class. */
 const SHAPE = {
 	"cssdoc-root": (id, l) => `${id}["${l}"]`,
@@ -853,10 +912,13 @@ function classify(node, isRoot, options) {
 		klass: "cssdoc-slot",
 		label: slot[1] ? `‹content: ${slot[1]}›` : "‹content›"
 	};
-	if (isRoot) return {
-		klass: "cssdoc-root",
-		label: node.selector
-	};
+	if (isRoot) {
+		const card = node.cardinality ? ` (${CARDINALITY_TOKEN[node.cardinality]})` : "";
+		return {
+			klass: "cssdoc-root",
+			label: `${node.selector}${card}`
+		};
+	}
 	const primary = firstClass(node.selector);
 	if (primary && primary !== options.self) {
 		const component = options.resolveComponent?.(primary);

package/dist/{lite-DtKEwRkS.d.mts → lite-DzhifijA.d.mts}

@@ -50,6 +50,12 @@ interface ModifierConvention {
    * of form/UI states, deliberately excluding ubiquitous interaction pseudos (`:hover`, `:focus`).
    */
   statePseudoClasses?: string[];
+  /**
+   * Native pseudo-elements (without the `::`) to document when they appear on a component's selectors,
+   * e.g. `["before", "after"]`. Defaults to {@link DEFAULT_PSEUDO_ELEMENTS} — a curated set of standard
+   * pseudo-elements, excluding vendor/experimental ones. Shadow `::part()` is handled separately.
+   */
+  pseudoElements?: string[];
   /**
    * Split the modifier body into `prop`/`value` on {@link ModifierConvention.propValueSeparator}?
    * Defaults to `false`. Ignored for `attribute` (which always derives `prop` from the attribute name
@@ -127,6 +133,8 @@ declare class ModifierMatcher {
   private readonly statePrefixes;
   /** Native pseudo-classes (no `:`) recognized as states. */
   private readonly statePseudoClasses;
+  /** Native pseudo-elements (no `::`) recognized as documented pseudo-elements. */
+  private readonly pseudoElements;
   constructor(convention: ModifierConvention);
   /** Does a class name (no leading dot) start with one of the convention's state prefixes? */
   private isStateClass;
@@ -180,6 +188,14 @@ declare class ModifierMatcher {
   pseudoStatesIn(selector: string): {
     name: string;
   }[];
+  /**
+   * Every native pseudo-element on the selector recognized for documentation — a `::name` whose `name`
+   * is in the convention's {@link ModifierConvention.pseudoElements} (e.g. `.alert::before` → `before`).
+   * `::part()`/`::slotted()` and pseudo-elements not in the set are ignored.
+   */
+  pseudoElementsIn(selector: string): {
+    name: string;
+  }[];
   /** Derive `prop`/`value` for a modifier `name` (as returned by {@link modifiersIn} or authored). */
   analyze(name: string): {
     prop: string;
@@ -283,6 +299,17 @@ interface CssState {
   /** Prose from a `@cssstate` doc tag, when authored. */
   description?: string;
 }
+/**
+ * A native pseudo-element a component styles (`::before`, `::marker`, `::selection`, …) — from a
+ * `@pseudo` doc tag or derived from a `::name` selector. Shadow `::part()` parts are modeled separately
+ * as {@link CssPart} (`shadowParts`), since only they map to a Custom Elements Manifest entry.
+ */
+interface CssPseudoElement {
+  /** The pseudo-element name without the leading `::`, e.g. `before`. */
+  name: string;
+  /** Prose from a `@pseudo` 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). */
@@ -367,6 +394,8 @@ interface StructureNode {
    * the stored selector.
    */
   cardinality?: "optional" | "many" | "one-or-more";
+  /** Prose from a `@wrapper` doc tag matching this node's class, when authored (annotates the node). */
+  description?: string;
   /** Child nodes (rules nested one brace level deeper). */
   children: StructureNode[];
 }
@@ -426,10 +455,17 @@ interface CssDocEntry {
   parts: CssPart[];
   /** Shadow-DOM exposed parts (`::part(name)`), from `@csspart` or a `::part()` selector. */
   shadowParts: CssPart[];
+  /** Native pseudo-elements the component styles (`::before`, `::marker`, …), from `@pseudo` or a selector. */
+  pseudoElements: CssPseudoElement[];
   /** States the component reacts to, from `@cssstate`, `:state()`, pseudo-classes, or state classes. */
   states: CssState[];
   /** Named slots the component shell exposes, from `@slot`. */
   slots: CssSlot[];
+  /**
+   * Internal to-do notes, from `@todo` tags and `/* @todo … *\/` inline comments. Development notes,
+   * not public API — emitters may omit them (like {@link CssDocEntry.privateRemarks}).
+   */
+  todos: string[];
   /**
    * Design tokens this component consumes: every `--*` custom property referenced via `var(...)` inside
    * its rules, each annotated with `@tokens` prose where authored (and including any `@tokens`-declared
@@ -553,16 +589,27 @@ declare class CssDocTagDefinition {
  * const model = parseCssDocs(css, { configuration: config });
  * ```
  */
+/**
+ * How a `/* … *\/` comment on a member's rule combines with the member's authored tag prose:
+ * `append` (tag then comment, the default), `prepend` (comment then tag), `replace` (comment wins when
+ * present), or `ignore` (comments are never used as descriptions).
+ */
+type InlineCommentMode = "append" | "prepend" | "replace" | "ignore";
 declare class CssDocConfiguration {
   private readonly _tagDefinitions;
   private readonly _byName;
   private readonly _supported;
   private _modifierConvention;
+  private _inlineComments;
   constructor();
   /** The resolved modifier convention this configuration parses with (defaults to BEM). */
   get modifierConvention(): ModifierConvention;
   /** Set the modifier convention from a preset name or a custom {@link ModifierConvention}. */
   setModifierConvention(input: ModifierConventionInput): void;
+  /** How inline `/* … *\/` comments combine with tag prose (defaults to `append`). */
+  get inlineComments(): InlineCommentMode;
+  /** Set the inline-comment combine mode. */
+  setInlineComments(mode: InlineCommentMode): void;
   /** Every registered tag definition, in registration order. */
   get tagDefinitions(): readonly CssDocTagDefinition[];
   /** Only the tag definitions that are currently supported. */
@@ -656,6 +703,12 @@ interface ParsedDoc {
   tokens: Map<string, string>;
   /** `@csspart` descriptions (shadow-DOM `::part()`), keyed by the bare part name (e.g. `header`). */
   cssParts: Map<string, string>;
+  /** `@pseudo` descriptions (native pseudo-elements), keyed by the bare name (e.g. `before`). */
+  pseudoElements: Map<string, string>;
+  /** `@wrapper` descriptions (optional-ancestor wrappers), keyed by the bare class (e.g. `badge-wrapper`). */
+  wrappers: Map<string, string>;
+  /** `@todo` notes (internal development notes). */
+  todos: string[];
   /** `@cssproperty` declarations. */
   cssProperties: DocCssProperty[];
   /** `@cssstate` descriptions, keyed by state name. */
@@ -768,4 +821,4 @@ declare function toMermaid(roots: StructureNode[], options?: MermaidOptions): st
  */
 declare function toJson(model: CssDocEntry[]): string;
 //#endregion
-export { CssState as A, ModifierMatcher as B, CssPart as C, CssReleaseStage as D, CssRelated as E, DEFAULT_STATE_PSEUDO_CLASSES as F, MODIFIER_PRESETS as I, ModifierConvention as L, ParseOptions as M, StructureNode as N, CssSlot as O, DEFAULT_MODIFIER_CONVENTION as P, ModifierConventionInput as R, CssParse as S, CssRecordKind as T, resolveModifierConvention as V, CssCondition as _, DocModifier as a, CssLayer as b, parseDocComment as c, stripCommentFraming as d, CssDocConfiguration as f, CssAnimation as g, CssDocTagDefinitionOptions as h, DocCssProperty as i, CssTokenConsumed as j, CssSource as k, parseStructure as l, CssDocTagDefinition as m, toMermaid as n, ParsedDoc as o, CssDocSyntaxKind as p, DocCondition as r, RECORD_TAGS as s, toJson as t, recordNameOf as u, CssDocEntry as v, CssPropertyDeclared as w, CssModifier as x, CssFunction as y, ModifierHit as z };
+export { CssSource as A, ModifierHit as B, CssParse as C, CssRelated as D, CssRecordKind as E, DEFAULT_MODIFIER_CONVENTION as F, resolveModifierConvention as H, DEFAULT_STATE_PSEUDO_CLASSES as I, MODIFIER_PRESETS as L, CssTokenConsumed as M, ParseOptions as N, CssReleaseStage as O, StructureNode as P, ModifierConvention as R, CssModifier as S, CssPropertyDeclared as T, ModifierMatcher as V, CssAnimation as _, DocModifier as a, CssFunction as b, parseDocComment as c, stripCommentFraming as d, CssDocConfiguration as f, InlineCommentMode as g, CssDocTagDefinitionOptions as h, DocCssProperty as i, CssState as j, CssSlot as k, parseStructure as l, CssDocTagDefinition as m, toMermaid as n, ParsedDoc as o, CssDocSyntaxKind as p, DocCondition as r, RECORD_TAGS as s, toJson as t, recordNameOf as u, CssCondition as v, CssPart as w, CssLayer as x, CssDocEntry as y, ModifierConventionInput as z };

package/dist/lite.d.mts

@@ -1,2 +1,2 @@
-import { A as CssState, B as ModifierMatcher, C as CssPart, D as CssReleaseStage, E as CssRelated, F as DEFAULT_STATE_PSEUDO_CLASSES, I as MODIFIER_PRESETS, L as ModifierConvention, M as ParseOptions, N as StructureNode, O as CssSlot, P as DEFAULT_MODIFIER_CONVENTION, R as ModifierConventionInput, S as CssParse, T as CssRecordKind, V as resolveModifierConvention, _ as CssCondition, a as DocModifier, b as CssLayer, c as parseDocComment, d as stripCommentFraming, f as CssDocConfiguration, g as CssAnimation, h as CssDocTagDefinitionOptions, i as DocCssProperty, j as CssTokenConsumed, k as CssSource, l as parseStructure, m as CssDocTagDefinition, n as toMermaid, o as ParsedDoc, p as CssDocSyntaxKind, r as DocCondition, s as RECORD_TAGS, t as toJson, u as recordNameOf, v as CssDocEntry, w as CssPropertyDeclared, x as CssModifier, y as CssFunction, z as ModifierHit } from "./lite-DtKEwRkS.mjs";
-export { type CssAnimation, type CssCondition, CssDocConfiguration, type CssDocEntry, type CssDocSyntaxKind, CssDocTagDefinition, type CssDocTagDefinitionOptions, type CssFunction, type CssLayer, type CssModifier, type CssParse, type CssPart, type CssPropertyDeclared, type CssRecordKind, type CssRelated, type CssReleaseStage, type CssSlot, type CssSource, type CssState, type CssTokenConsumed, DEFAULT_MODIFIER_CONVENTION, DEFAULT_STATE_PSEUDO_CLASSES, type DocCondition, type DocCssProperty, type DocModifier, MODIFIER_PRESETS, type ModifierConvention, type ModifierConventionInput, type ModifierHit, ModifierMatcher, type ParseOptions, type ParsedDoc, RECORD_TAGS, type StructureNode, parseDocComment, parseStructure, recordNameOf, resolveModifierConvention, stripCommentFraming, toJson, toMermaid };
+import { A as CssSource, B as ModifierHit, C as CssParse, D as CssRelated, E as CssRecordKind, F as DEFAULT_MODIFIER_CONVENTION, H as resolveModifierConvention, I as DEFAULT_STATE_PSEUDO_CLASSES, L as MODIFIER_PRESETS, M as CssTokenConsumed, N as ParseOptions, O as CssReleaseStage, P as StructureNode, R as ModifierConvention, S as CssModifier, T as CssPropertyDeclared, V as ModifierMatcher, _ as CssAnimation, a as DocModifier, b as CssFunction, c as parseDocComment, d as stripCommentFraming, f as CssDocConfiguration, g as InlineCommentMode, h as CssDocTagDefinitionOptions, i as DocCssProperty, j as CssState, k as CssSlot, l as parseStructure, m as CssDocTagDefinition, n as toMermaid, o as ParsedDoc, p as CssDocSyntaxKind, r as DocCondition, s as RECORD_TAGS, t as toJson, u as recordNameOf, v as CssCondition, w as CssPart, x as CssLayer, y as CssDocEntry, z as ModifierConventionInput } from "./lite-DzhifijA.mjs";
+export { type CssAnimation, type CssCondition, CssDocConfiguration, type CssDocEntry, type CssDocSyntaxKind, CssDocTagDefinition, type CssDocTagDefinitionOptions, type CssFunction, type CssLayer, type CssModifier, type CssParse, type CssPart, type CssPropertyDeclared, type CssRecordKind, type CssRelated, type CssReleaseStage, type CssSlot, type CssSource, type CssState, type CssTokenConsumed, DEFAULT_MODIFIER_CONVENTION, DEFAULT_STATE_PSEUDO_CLASSES, type DocCondition, type DocCssProperty, type DocModifier, type InlineCommentMode, MODIFIER_PRESETS, type ModifierConvention, type ModifierConventionInput, type ModifierHit, ModifierMatcher, type ParseOptions, type ParsedDoc, RECORD_TAGS, type StructureNode, parseDocComment, parseStructure, recordNameOf, resolveModifierConvention, stripCommentFraming, toJson, toMermaid };

package/dist/lite.mjs

@@ -1,2 +1,2 @@
-import { a as parseStructure, c as CssDocConfiguration, d as DEFAULT_STATE_PSEUDO_CLASSES, f as MODIFIER_PRESETS, i as parseDocComment, l as CssDocTagDefinition, m as resolveModifierConvention, n as toMermaid, o as recordNameOf, p as ModifierMatcher, r as RECORD_TAGS, s as stripCommentFraming, t as toJson, u as DEFAULT_MODIFIER_CONVENTION } from "./lite-HEYG01Eo.mjs";
+import { a as parseStructure, c as CssDocConfiguration, d as DEFAULT_STATE_PSEUDO_CLASSES, f as MODIFIER_PRESETS, i as parseDocComment, l as CssDocTagDefinition, m as resolveModifierConvention, n as toMermaid, o as recordNameOf, p as ModifierMatcher, r as RECORD_TAGS, s as stripCommentFraming, t as toJson, u as DEFAULT_MODIFIER_CONVENTION } from "./lite-CEVmwLGF.mjs";
 export { CssDocConfiguration, CssDocTagDefinition, DEFAULT_MODIFIER_CONVENTION, DEFAULT_STATE_PSEUDO_CLASSES, MODIFIER_PRESETS, ModifierMatcher, RECORD_TAGS, parseDocComment, parseStructure, recordNameOf, resolveModifierConvention, stripCommentFraming, toJson, toMermaid };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cssdoc/core",
-  "version": "0.5.3",
+  "version": "0.6.0",
   "description": "A generic CSS documentation extractor: parse doc-comments + the CSS AST into a serializable model (TSDoc, for CSS).",
   "keywords": [
     "css",
@@ -32,8 +32,8 @@
     "access": "public"
   },
   "dependencies": {
-    "postcss": "^8.5.17",
-    "@cssdoc/spec": "0.5.3"
+    "postcss": "^8.5.19",
+    "@cssdoc/spec": "0.6.0"
   },
   "devDependencies": {
     "@types/node": "^24.13.3",