moss_core/contract/

components.rs

//! moss component contract — Source 2 of the federated contract.
//!
//! Single source of truth for every `moss-*` class moss currently emits.
//! Each entry declares: the class name, its kind (container/instance/standalone/chrome),
//! accepted `data-*` attributes with value spaces, example HTML, example markdown.
//!
//! ## Adding a new emitter class
//!
//! 1. Emit the class from your renderer module (`build/markdown/*`, `build/components/*`).
//! 2. Add a `ComponentEntry` to [`COMPONENTS`] here.
//! 3. Run `cargo test --test components_sync_test` from src-tauri/ — the
//!    scanner test will fail if you forget.
//! 4. Run `cargo run --bin generate-artifacts --features dev-tools -- contract-docs` to
//!    refresh `docs/reference/contract.md`.
//!
//! ## Why a const table, not a derive macro?
//!
//! Mirrors the BUILTIN_FIELDS precedent in `schema_fields.rs`. The synchronization
//! is enforced by a sync test (`emitter_classes_match_components_table`) that
//! scans emitter Rust source for `class="moss-..."` literals. This is a
//! best-effort scanner (won't catch classes assembled via `format!()`), not a
//! type-checked guarantee like BUILTIN_FIELDS' compile-time mirror. The
//! limitation is documented in the spec § Source 2.

/// Status of a component entry.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Status {
    /// In active use; theme authors can rely on it.
    Confirmed,
    /// Emerging convention; may evolve.
    Emerging,
    /// Scheduled for removal; theme authors should migrate.
    Retired,
}

/// A declared `data-*` attribute on a component.
pub struct DataAttr {
    /// Attribute name including `data-` prefix (e.g. `"data-layout"`).
    pub name: &'static str,
    /// Allowed values (e.g. `&["grid", "list", "minimal"]`). Empty means free-form.
    pub values: &'static [&'static str],
    /// Default value (first in `values`, or `""` for free-form).
    pub default: &'static str,
    /// Short description shown in reference.md.
    pub description: &'static str,
}

/// A single component contract entry.
pub struct ComponentEntry {
    /// Class name without leading `.` (e.g. `"moss-cards"`).
    pub class: &'static str,
    /// Container / Instance / Standalone / Chrome.
    pub kind: &'static str,
    /// For Instance kinds, the parent container's class (or `""`).
    pub parent: &'static str,
    /// Declared `data-*` attributes on the element with this class.
    pub data_attrs: &'static [DataAttr],
    /// Example HTML snippet showing the class in context. Multi-line allowed.
    pub example_html: &'static str,
    /// Example markdown that produces this HTML. Empty for HTML-only chrome.
    pub example_markdown: &'static str,
    /// Status: confirmed / emerging / retired.
    pub status: Status,
    /// Contract version this entry was introduced in.
    pub since: &'static str,
    /// Optional human-readable description.
    pub description: &'static str,
}

/// Classes in [`COMPONENTS`] that deliberately carry no `moss-` prefix.
///
/// Every other entry must be `moss-`-prefixed; `every_component_has_a_class_name`
/// enforces that and consults this list for the exceptions. The list lives here,
/// beside the table, rather than in the test: an unprefixed class is a decision
/// made when the entry is *written*, and a reviewer reading the entry has to be
/// able to see that the decision was made. It was in the test file until
/// 2026-08-06, and the split cost a red build — declaring the masthead and nav
/// interior added 21 unprefixed entries whose exemption had to be recorded in a
/// file nobody editing the table had open.
///
/// Two families, both emitted for **theme parity** — themes written against
/// these names predate the `moss-` convention, so renaming them would break
/// styling moss does not own:
///
/// - Obsidian-style callouts (`callout`, `callout-<type>`), emitted alongside
///   their `moss-callout` equivalents.
/// - The nav interior and article masthead (`main-nav`, `date-line`, …).
///
/// Prefix matching is deliberate for the callout family only: `callout-<type>`
/// is an open set that grows with the callout vocabulary. The chrome names are
/// a closed set and are listed exactly, so a typo'd new one still fails.
pub const UNPREFIXED_LEGACY_CLASSES: &[&str] = &[
    // Obsidian callout parity — `callout-*` is matched by prefix, see below.
    "callout",
    // Nav interior.
    "main-nav",
    "nav-left",
    "nav-right",
    "nav-links",
    "nav-icons",
    "nav-search-btn",
    "nav-theme-btn",
    "nav-lang-toggle",
    "nav-lang-current",
    "nav-lang-link",
    "search-icon",
    "theme-toggle-icon",
    "mobile-menu-button",
    "site-name",
    "site-logo",
    "breadcrumb-segment",
    "breadcrumb-label",
    "breadcrumb-separator",
    // Article masthead.
    "date-line",
    "date",
    // Default footer.
    "footer-default",
    "footer-link",
    // Surfaces the site JavaScript reads (declared 2026-08-09). Same reason as
    // the nav: these names were emitted, styled, and queried by name long before
    // the `moss-` convention, and a theme that targets them today would break if
    // they were renamed for tidiness.
    "container",
    "nav-content",
    "font-anchor",
    "font-trigger",
    "cover-thumb",
    "media-item",
    "lightbox-content",
    "lightbox-image",
    "lightbox-video",
    "lightbox-iframe",
    "lightbox-title",
    "lightbox-article-link",
    "lightbox-close",
    "lightbox-next",
    "lightbox-prev",
    "comments-toggle",
    "comment-list",
    "comment-item",
    "comment-replies",
    "comment-reply-btn",
];

/// Whether `class` is exempt from the `moss-` prefix rule.
///
/// See [`UNPREFIXED_LEGACY_CLASSES`]. The `callout-` prefix arm covers the
/// open-ended Obsidian callout types (`callout-note`, `callout-warning`, …).
pub fn is_unprefixed_legacy(class: &str) -> bool {
    class.starts_with("callout-") || UNPREFIXED_LEGACY_CLASSES.contains(&class)
}

/// The full contract surface — every `moss-*` class moss currently emits.
///
/// Phase 0b seeds this with the CURRENT emitted vocabulary (not the
/// v1-collapsed shape). Phase 1c rewrites to the collapsed form.
pub const COMPONENTS: &[ComponentEntry] = &[
    ComponentEntry {
        class: "moss-cards",
        kind: "container",
        parent: "",
        data_attrs: &[
            DataAttr {
                name: "data-layout",
                values: &["grid", "list", "minimal"],
                default: "grid",
                description: "Card layout density. Grid: 2-3 cols with covers. List: single column with side covers. Minimal: text-only with year groupings.",
            },
            DataAttr {
                name: "data-density",
                values: &["default", "compact"],
                default: "default",
                description: "Vertical spacing density.",
            },
            DataAttr {
                name: "data-list-axis",
                values: &["date", "weight", "title"],
                default: "title",
                description: "Sort axis for the listing (mirrors the folder's `sort:` frontmatter). Drives `--moss-card-min` density tuning and decides whether each `.moss-card-meta` slot is filled (date axis) or omitted (weight/title axes).",
            },
            DataAttr {
                name: "data-list-has-covers",
                values: &[""],
                default: "",
                description: "Boolean presence flag: emitted iff any child card has a cover. Combines with `data-list-axis` to widen `--moss-card-min` for cover-led layouts. Use `[data-list-has-covers]` in CSS to target it.",
            },
        ],
        example_html: r#"<div class="moss-cards-container">
  <div class="moss-cards" data-layout="grid" data-list-axis="date" data-list-has-covers>
    <a class="moss-card" href="...">...</a>
    <a class="moss-card" href="...">...</a>
  </div>
</div>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "1",
        description: "Auto-generated listing of child pages. The single canonical container; layout density on `data-layout` (`grid` for cover-led tiles, `list` for cover+excerpt rows, `minimal` for text-only year-grouped indexes). Wrapped in `.moss-cards-container` to scope CSS container queries.",
    },
    ComponentEntry {
        class: "moss-cards-container",
        kind: "container",
        parent: "",
        data_attrs: &[],
        example_html: r#"<div class="moss-cards-container">
  <div class="moss-cards" data-layout="grid">...</div>
</div>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "1",
        description: "Outer wrapper around `.moss-cards` that carries `container-type: inline-size` so the grid can use `@container` queries instead of viewport `@media` queries. Layout-agnostic — wraps any `data-layout` variant.",
    },
    ComponentEntry {
        class: "moss-summary-layout",
        kind: "container",
        parent: "moss-cards",
        data_attrs: &[],
        example_html: r#"<div class="moss-cards" data-layout="list">...</div>"#,
        example_markdown: "",
        status: Status::Retired,
        since: "1",
        description: "Retired: the additional co-class on `.moss-cards[data-layout=\"list\"]` had no matching rules in the default CSS once `children_style: summary` collapsed into the list-layout block, and its lingering emission broke themes that hid the class (e.g. SoCiviC's `.moss/theme/style.css` keyed `display: none` on it, erasing folder-embed listings). Theme authors targeting summary listings should use `.moss-cards[data-layout=\"list\"]` directly.",
    },
    // -------------------------------------------------------------------
    // Cards family — current emitted vocabulary (pre-Phase 1c collapsing).
    // Three parallel layouts: grid, list, minimal. Each has its own
    // container + instance + sub-classes.
    // -------------------------------------------------------------------
    ComponentEntry {
        class: "moss-cards-grid",
        kind: "container",
        parent: "",
        data_attrs: &[],
        example_html: r#"<div class="moss-cards-grid">
  <a class="moss-card-grid" href="...">...</a>
</div>"#,
        example_markdown: "",
        status: Status::Retired,
        since: "0",
        description: "Retired in Phase 1c — collapsed into `.moss-cards[data-layout=grid]`.",
    },
    ComponentEntry {
        class: "moss-cards-list",
        kind: "container",
        parent: "",
        data_attrs: &[],
        example_html: r#"<div class="moss-cards-list">
  <a class="moss-card-list" href="...">...</a>
</div>"#,
        example_markdown: "",
        status: Status::Retired,
        since: "0",
        description: "Retired in Phase 1c — collapsed into `.moss-cards[data-layout=list]`.",
    },
    ComponentEntry {
        class: "moss-cards-minimal-year-group",
        kind: "container",
        parent: "",
        data_attrs: &[],
        example_html: r#"<section class="moss-cards-minimal-year-group">
  <h3>2024</h3>
  <div class="moss-card-minimal">...</div>
</section>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "Year-grouped section in minimal card layout (e.g. blog index). Modifier `--summary` collapses past years.",
    },
    ComponentEntry {
        class: "moss-cards-minimal-year-group--summary",
        kind: "container",
        parent: "moss-cards-minimal-year-group",
        data_attrs: &[],
        example_html: r#"<section class="moss-cards-minimal-year-group moss-cards-minimal-year-group--summary">...</section>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "BEM modifier on `.moss-cards-minimal-year-group`. Applied to year groups that should render in collapsed summary form (e.g. past years on a blog index).",
    },
    ComponentEntry {
        class: "moss-card",
        kind: "instance",
        parent: "moss-cards",
        data_attrs: &[
            DataAttr {
                name: "data-linkblog",
                values: &[],
                default: "",
                description: "Presence flag: emitted IFF the card's source page has an `external_url:` frontmatter (linkblog pattern). When set, the element is a `<div>` rather than `<a>` so the kicker can host a nested `<a>★</a>` archive link; title, cover, and description carry their own inner anchors to the canonical URL. Absent on ordinary cards (single whole-card `<a>`).",
            },
            DataAttr {
                name: "data-cover-color",
                values: &[],
                default: "",
                description: "Presence flag: emitted IFF the cover-colour ladder produced a colour, which arrives alongside it as `--moss-cover-color` in the element's `style`. Absent for a card with no cover, and for an image cover whose file moss could not read.",
            },
        ],
        example_html: r#"<a class="moss-card" href="...">...</a>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "1",
        description: "v1 collapsed shape — single canonical instance class inside `.moss-cards`. Layout-specific styling targets `.moss-cards[data-layout=X] .moss-card`. Tag is `<a>` for ordinary cards and `<div>` for linkblog cards (`[data-linkblog]`).",
    },
    ComponentEntry {
        class: "moss-card-cover",
        kind: "instance",
        parent: "moss-card",
        data_attrs: &[],
        example_html: r#"<div class="moss-card-cover"><img src="..." /></div>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "1",
        description: "Cover media slot inside `.moss-card`. Gets `.moss-card-no-cover` modifier when no image is present.",
    },
    ComponentEntry {
        class: "moss-card-no-cover",
        kind: "instance",
        parent: "moss-card",
        data_attrs: &[],
        example_html: r#"<div class="moss-card-cover moss-card-no-cover"></div>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "1",
        description: "Modifier applied to `.moss-card-cover` when no cover media is available.",
    },
    ComponentEntry {
        class: "moss-card-content",
        kind: "instance",
        parent: "moss-card",
        data_attrs: &[],
        example_html: r#"<div class="moss-card-content">...</div>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "1",
        description: "Text content slot inside a grid-layout `.moss-card` (kicker + title + meta).",
    },
    ComponentEntry {
        class: "moss-card-row",
        kind: "instance",
        parent: "moss-card",
        data_attrs: &[],
        example_html: r#"<div class="moss-card-row">...</div>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "1",
        description: "Row wrapper inside a list-layout `.moss-card` holding body + cover side-by-side.",
    },
    ComponentEntry {
        class: "moss-card-body",
        kind: "instance",
        parent: "moss-card",
        data_attrs: &[],
        example_html: r#"<div class="moss-card-body">...</div>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "1",
        description: "Text body slot of a list-layout `.moss-card`.",
    },
    ComponentEntry {
        class: "moss-card-head",
        kind: "instance",
        parent: "moss-card",
        data_attrs: &[],
        example_html: r#"<div class="moss-card-head">...</div>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "1",
        description: "Header row of a `.moss-card-body` (title + kicker + meta).",
    },
    ComponentEntry {
        class: "moss-card-title",
        kind: "instance",
        parent: "moss-card",
        data_attrs: &[],
        example_html: r#"<h3 class="moss-card-title">Page title</h3>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "1",
        description: "Title inside `.moss-card`.",
    },
    ComponentEntry {
        class: "moss-card-meta",
        kind: "instance",
        parent: "moss-card",
        data_attrs: &[],
        example_html: r#"<div class="moss-card-meta">2024-01-15</div>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "1",
        description: "Type-aware metadata slot (date for articles, count for folders, domain for links). Renders ABOVE the title in horizontal mode — filling the kicker position when the explicit `kicker` slot is unset, per `docs/reference/design/preview-cards.md:22-30`. To the right of the title in vertical CJK mode (the horizontal kicker position transposed). Meta IS the visual kicker, with the same uppercase overline treatment.",
    },
    ComponentEntry {
        class: "moss-card-kicker",
        kind: "instance",
        parent: "moss-card",
        data_attrs: &[],
        example_html: r#"<span class="moss-card-kicker">Category</span>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "1",
        description: "Eyebrow / overline above the title inside `.moss-card`.",
    },
    ComponentEntry {
        class: "moss-card-permalink",
        kind: "instance",
        parent: "moss-card-kicker",
        data_attrs: &[],
        example_html: r#"<a class="moss-card-permalink" href="/posts/foo/" title="Permalink to 'Title'">★</a>"#,
        example_markdown: "",
        status: Status::Emerging,
        since: "1",
        description: "Author's-archive link mark (★, U+2605) emitted INSIDE `.moss-card-kicker` for linkblog cards (those whose child page has `external_url:`). The card title links to the external canonical (publisher); the `★` links to the local archival copy at the page's slug. Reads as part of the kicker line — \"Publisher · Year ★\". Semantically distinct from Daring-Fireball's linkblog ★ (which marks discussion permalink alongside commentary) — here the local copy is the same content preserved for resilience and stable bylines, not added commentary. Putting `<a>★</a>` inside the kicker is valid because linkblog cards emit `<div class=\"moss-card\" data-linkblog>` (not `<a>`) as the outer element — see the `data-linkblog` attribute described on `.moss-card`.",
    },
    ComponentEntry {
        class: "moss-card-title-link",
        kind: "instance",
        parent: "moss-card-head",
        data_attrs: &[],
        example_html: r#"<a class="moss-card-title-link" href="https://outlet.example/article"><h3 class="moss-card-title">Article Title</h3></a>"#,
        example_markdown: "",
        status: Status::Emerging,
        since: "1",
        description: "Anchor wrapping the `.moss-card-title` `<h3>` on linkblog cards. Ordinary cards have the whole-card `<a class=\"moss-card\">` as the link target — but linkblog cards switch the outer to `<div>` so the kicker can host a nested `★` anchor, which means the title needs its own anchor to stay clickable. Same canonical-URL target as the other inner anchors (`moss-card-cover-link`, `moss-card-description-link`).",
    },
    ComponentEntry {
        class: "moss-card-cover-link",
        kind: "instance",
        parent: "moss-card-row",
        data_attrs: &[],
        example_html: r#"<a class="moss-card-cover-link" href="https://outlet.example/article"><div class="moss-card-cover">...</div></a>"#,
        example_markdown: "",
        status: Status::Emerging,
        since: "1",
        description: "Anchor wrapping the `.moss-card-cover` on linkblog cards — same role as `.moss-card-title-link` but for the cover image / media. Targets the canonical (external) URL.",
    },
    ComponentEntry {
        class: "moss-card-description-link",
        kind: "instance",
        parent: "moss-card-body",
        data_attrs: &[],
        example_html: r#"<a class="moss-card-description-link" href="https://outlet.example/article"><p class="moss-card-description">…</p></a>"#,
        example_markdown: "",
        status: Status::Emerging,
        since: "1",
        description: "Anchor wrapping the `.moss-card-description` on linkblog cards — same role as `.moss-card-title-link` but for the description excerpt. Targets the canonical (external) URL.",
    },
    ComponentEntry {
        class: "moss-card-description",
        kind: "instance",
        parent: "moss-card",
        data_attrs: &[],
        example_html: r#"<p class="moss-card-description">Excerpt...</p>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "1",
        description: "Excerpt / description paragraph inside a `.moss-card` — below the title in both grid- and list-layout cards.",
    },
    ComponentEntry {
        class: "moss-card-count",
        kind: "instance",
        parent: "moss-card",
        data_attrs: &[],
        example_html: r#"<div class="moss-card-count">4 articles</div>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "1",
        description: "Tertiary subtitle line showing `N articles` for a folder card. Renders only on non-date listings when the folder card has no `description` to display.",
    },
    ComponentEntry {
        class: "moss-embed-more",
        kind: "instance",
        parent: "moss-cards-container",
        data_attrs: &[],
        example_html: r#"<p class="moss-embed-more"><a href="/news/">More →</a></p>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "1",
        description: "Trailing \"More →\" link on a truncated children listing (emitted when `children_limit` caps the embed); links to the folder's full index. Rendered as a sibling immediately after `.moss-cards-container`, so it sits outside the listing's flex `gap` and binds to the list via its own `margin-top` (see docs/reference/design/spacing.md).",
    },
    ComponentEntry {
        class: "moss-card-grid",
        kind: "instance",
        parent: "moss-cards-grid",
        data_attrs: &[],
        example_html: r#"<a class="moss-card-grid" href="...">...</a>"#,
        example_markdown: "",
        status: Status::Retired,
        since: "0",
        description: "Retired in Phase 1c — collapsed into `.moss-card` (with parent `.moss-cards[data-layout=grid]`).",
    },
    ComponentEntry {
        class: "moss-card-grid-cover",
        kind: "instance",
        parent: "moss-card-grid",
        data_attrs: &[],
        example_html: r#"<div class="moss-card-grid-cover"><img src="..." /></div>"#,
        example_markdown: "",
        status: Status::Retired,
        since: "0",
        description: "Retired in Phase 1c — collapsed into `.moss-card-cover`.",
    },
    ComponentEntry {
        class: "moss-card-grid-no-cover",
        kind: "instance",
        parent: "moss-card-grid",
        data_attrs: &[],
        example_html: r#"<div class="moss-card-grid-cover moss-card-grid-no-cover"></div>"#,
        example_markdown: "",
        status: Status::Retired,
        since: "0",
        description: "Retired in Phase 1c — collapsed into `.moss-card-no-cover`.",
    },
    ComponentEntry {
        class: "moss-card-grid-content",
        kind: "instance",
        parent: "moss-card-grid",
        data_attrs: &[],
        example_html: r#"<div class="moss-card-grid-content">...</div>"#,
        example_markdown: "",
        status: Status::Retired,
        since: "0",
        description: "Retired in Phase 1c — collapsed into `.moss-card-content`.",
    },
    ComponentEntry {
        class: "moss-card-grid-kicker",
        kind: "instance",
        parent: "moss-card-grid",
        data_attrs: &[],
        example_html: r#"<span class="moss-card-grid-kicker">Category</span>"#,
        example_markdown: "",
        status: Status::Retired,
        since: "0",
        description: "Retired in Phase 1c — collapsed into `.moss-card-kicker`.",
    },
    ComponentEntry {
        class: "moss-card-grid-title",
        kind: "instance",
        parent: "moss-card-grid",
        data_attrs: &[],
        example_html: r#"<h3 class="moss-card-grid-title">Page title</h3>"#,
        example_markdown: "",
        status: Status::Retired,
        since: "0",
        description: "Retired in Phase 1c — collapsed into `.moss-card-title`.",
    },
    ComponentEntry {
        class: "moss-card-grid-meta",
        kind: "instance",
        parent: "moss-card-grid",
        data_attrs: &[],
        example_html: r#"<div class="moss-card-grid-meta">2024-01-15</div>"#,
        example_markdown: "",
        status: Status::Retired,
        since: "0",
        description: "Retired in Phase 1c — collapsed into `.moss-card-meta`.",
    },
    ComponentEntry {
        class: "moss-card-list",
        kind: "instance",
        parent: "moss-cards-list",
        data_attrs: &[],
        example_html: r#"<a class="moss-card-list" href="...">...</a>"#,
        example_markdown: "",
        status: Status::Retired,
        since: "0",
        description: "Retired in Phase 1c — collapsed into `.moss-card` (with parent `.moss-cards[data-layout=list]`).",
    },
    ComponentEntry {
        class: "moss-card-list-row",
        kind: "instance",
        parent: "moss-card-list",
        data_attrs: &[],
        example_html: r#"<div class="moss-card-list-row">...</div>"#,
        example_markdown: "",
        status: Status::Retired,
        since: "0",
        description: "Retired in Phase 1c — collapsed into `.moss-card-row`.",
    },
    ComponentEntry {
        class: "moss-card-list-cover",
        kind: "instance",
        parent: "moss-card-list",
        data_attrs: &[],
        example_html: r#"<div class="moss-card-list-cover"><img src="..." /></div>"#,
        example_markdown: "",
        status: Status::Retired,
        since: "0",
        description: "Retired in Phase 1c — collapsed into `.moss-card-cover`.",
    },
    ComponentEntry {
        class: "moss-card-list-body",
        kind: "instance",
        parent: "moss-card-list",
        data_attrs: &[],
        example_html: r#"<div class="moss-card-list-body">...</div>"#,
        example_markdown: "",
        status: Status::Retired,
        since: "0",
        description: "Retired in Phase 1c — collapsed into `.moss-card-body`.",
    },
    ComponentEntry {
        class: "moss-card-list-head",
        kind: "instance",
        parent: "moss-card-list",
        data_attrs: &[],
        example_html: r#"<div class="moss-card-list-head">...</div>"#,
        example_markdown: "",
        status: Status::Retired,
        since: "0",
        description: "Retired in Phase 1c — collapsed into `.moss-card-head`.",
    },
    ComponentEntry {
        class: "moss-card-list-kicker",
        kind: "instance",
        parent: "moss-card-list",
        data_attrs: &[],
        example_html: r#"<span class="moss-card-list-kicker">Category</span>"#,
        example_markdown: "",
        status: Status::Retired,
        since: "0",
        description: "Retired in Phase 1c — collapsed into `.moss-card-kicker`.",
    },
    ComponentEntry {
        class: "moss-card-list-title",
        kind: "instance",
        parent: "moss-card-list",
        data_attrs: &[],
        example_html: r#"<h3 class="moss-card-list-title">Page title</h3>"#,
        example_markdown: "",
        status: Status::Retired,
        since: "0",
        description: "Retired in Phase 1c — collapsed into `.moss-card-title`.",
    },
    ComponentEntry {
        class: "moss-card-list-meta",
        kind: "instance",
        parent: "moss-card-list",
        data_attrs: &[],
        example_html: r#"<div class="moss-card-list-meta">2024-01-15</div>"#,
        example_markdown: "",
        status: Status::Retired,
        since: "0",
        description: "Retired in Phase 1c — collapsed into `.moss-card-meta`.",
    },
    ComponentEntry {
        class: "moss-card-list-description",
        kind: "instance",
        parent: "moss-card-list",
        data_attrs: &[],
        example_html: r#"<p class="moss-card-list-description">Excerpt...</p>"#,
        example_markdown: "",
        status: Status::Retired,
        since: "0",
        description: "Retired in Phase 1c — collapsed into `.moss-card-description`.",
    },
    ComponentEntry {
        class: "moss-card-minimal",
        kind: "instance",
        parent: "moss-cards-minimal-year-group",
        data_attrs: &[],
        example_html: r#"<div class="moss-card-minimal">
  <a class="moss-prefix-link" href="...">...</a>
</div>"#,
        example_markdown: "",
        status: Status::Retired,
        since: "0",
        description: "Retired in Phase 1c — collapsed into `.moss-card` (with parent `.moss-cards[data-layout=minimal]`).",
    },
    ComponentEntry {
        class: "moss-folder-item",
        kind: "instance",
        parent: "moss-cards-minimal-year-group",
        data_attrs: &[],
        example_html: r#"<div class="moss-card-minimal moss-folder-item">
  <a class="moss-prefix-link moss-folder-link" href="...">...</a>
  <p class="moss-folder-description">...</p>
</div>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "Modifier on `.moss-card-minimal` for folder-type entries in minimal listings.",
    },
    ComponentEntry {
        class: "moss-folder-title",
        kind: "instance",
        parent: "moss-folder-item",
        data_attrs: &[],
        example_html: r#"<span class="moss-folder-title">Folder name</span>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "Title text of a folder entry in minimal listings.",
    },
    ComponentEntry {
        class: "moss-folder-description",
        kind: "instance",
        parent: "moss-folder-item",
        data_attrs: &[],
        example_html: r#"<p class="moss-folder-description">Description...</p>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "Description paragraph of a folder entry in minimal listings.",
    },
    ComponentEntry {
        class: "moss-folder-link",
        kind: "instance",
        parent: "moss-folder-item",
        data_attrs: &[],
        example_html: r#"<a class="moss-prefix-link moss-folder-link" href="...">...</a>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "Modifier on `.moss-prefix-link` for folder-type links in minimal listings.",
    },
    // -------------------------------------------------------------------
    // Prefix-link primitive — used by minimal cards and other listings.
    // -------------------------------------------------------------------
    ComponentEntry {
        class: "moss-prefix-link",
        kind: "instance",
        parent: "moss-card-minimal",
        data_attrs: &[],
        example_html: r#"<a class="moss-prefix-link" href="...">
  <span class="moss-prefix-link-prefix">2024-01-15</span>
  <span class="moss-prefix-link-title">Page title</span>
</a>"#,
        example_markdown: "",
        status: Status::Emerging,
        since: "0",
        description: "Link with a prefix span (date or icon) and a title span. Used inside minimal cards.",
    },
    ComponentEntry {
        class: "moss-prefix-link-prefix",
        kind: "instance",
        parent: "moss-prefix-link",
        data_attrs: &[],
        example_html: r#"<span class="moss-prefix-link-prefix">2024-01-15</span>"#,
        example_markdown: "",
        status: Status::Emerging,
        since: "0",
        description: "Prefix slot of a prefix-link (typically a date).",
    },
    ComponentEntry {
        class: "moss-prefix-link-title",
        kind: "instance",
        parent: "moss-prefix-link",
        data_attrs: &[],
        example_html: r#"<span class="moss-prefix-link-title">Page title</span>"#,
        example_markdown: "",
        status: Status::Emerging,
        since: "0",
        description: "Title slot of a prefix-link.",
    },
    ComponentEntry {
        class: "moss-prefix-link-suffix",
        kind: "instance",
        parent: "moss-prefix-link",
        data_attrs: &[],
        example_html: r#"<span class="moss-prefix-link-suffix">→</span>"#,
        example_markdown: "",
        status: Status::Emerging,
        since: "0",
        description: "Optional trailing slot of a prefix-link.",
    },
    // -------------------------------------------------------------------
    // Callouts — Obsidian-style admonitions. Type variant goes on the
    // container as `.callout-<type>`. Phase 1c may collapse into
    // `.moss-callout[data-type]`.
    // -------------------------------------------------------------------
    ComponentEntry {
        class: "moss-callout",
        kind: "standalone",
        parent: "",
        data_attrs: &[],
        example_html: r#"<div class="moss-callout callout" data-type="note">
  <div class="callout-title">Note</div>
  <div class="callout-content">Body...</div>
</div>"#,
        example_markdown: "> [!note]\n> Body...",
        status: Status::Confirmed,
        since: "0",
        description: "Obsidian-style callout. The Obsidian-compat `.callout` class is co-emitted; type lives on `data-type` (v1).",
    },
    ComponentEntry {
        class: "callout",
        kind: "standalone",
        parent: "",
        data_attrs: &[
            DataAttr {
                name: "data-type",
                values: &["note", "info", "tip", "warning", "pending"],
                default: "note",
                description: "v1 callout type. Theme authors target `.callout[data-type=...]` to style by variant.",
            },
        ],
        example_html: r#"<div class="moss-callout callout" data-type="note">...</div>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "Obsidian-compat class co-emitted on every callout for theme parity. Type lives on `data-type` (v1).",
    },
    ComponentEntry {
        class: "callout-title",
        kind: "instance",
        parent: "moss-callout",
        data_attrs: &[],
        example_html: r#"<div class="callout-title">Note</div>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "Title row of a callout.",
    },
    ComponentEntry {
        class: "callout-content",
        kind: "instance",
        parent: "moss-callout",
        data_attrs: &[],
        example_html: r#"<div class="callout-content">Body...</div>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "Body container of a callout.",
    },
    ComponentEntry {
        class: "callout-note",
        kind: "instance",
        parent: "moss-callout",
        data_attrs: &[],
        example_html: r#"<div class="moss-callout callout callout-note">...</div>"#,
        example_markdown: "> [!note]\n> Body",
        status: Status::Retired,
        since: "0",
        description: "Retired in Phase 1c — type lives on `.callout[data-type=note]`.",
    },
    ComponentEntry {
        class: "callout-info",
        kind: "instance",
        parent: "moss-callout",
        data_attrs: &[],
        example_html: r#"<div class="moss-callout callout callout-info">...</div>"#,
        example_markdown: "> [!info]\n> Body",
        status: Status::Retired,
        since: "0",
        description: "Retired in Phase 1c — type lives on `.callout[data-type=info]`.",
    },
    ComponentEntry {
        class: "callout-tip",
        kind: "instance",
        parent: "moss-callout",
        data_attrs: &[],
        example_html: r#"<div class="moss-callout callout callout-tip">...</div>"#,
        example_markdown: "> [!tip]\n> Body",
        status: Status::Retired,
        since: "0",
        description: "Retired in Phase 1c — type lives on `.callout[data-type=tip]`.",
    },
    ComponentEntry {
        class: "callout-warning",
        kind: "instance",
        parent: "moss-callout",
        data_attrs: &[],
        example_html: r#"<div class="moss-callout callout callout-warning">...</div>"#,
        example_markdown: "> [!warning]\n> Body",
        status: Status::Retired,
        since: "0",
        description: "Retired in Phase 1c — type lives on `.callout[data-type=warning]`.",
    },
    ComponentEntry {
        class: "callout-pending",
        kind: "instance",
        parent: "moss-callout",
        data_attrs: &[],
        example_html: r#"<div class="moss-callout callout callout-pending">...</div>"#,
        example_markdown: "> [!pending]\n> Body",
        status: Status::Retired,
        since: "0",
        description: "Retired in Phase 1c — type lives on `.callout[data-type=pending]`.",
    },
    // -------------------------------------------------------------------
    // Embeds — `![[file.ext]]` shortcode renderers (audio, video, pdf,
    // notebook, table, 3d, iframe).
    // -------------------------------------------------------------------
    ComponentEntry {
        class: "moss-embed",
        kind: "standalone",
        parent: "",
        data_attrs: &[
            DataAttr {
                name: "data-type",
                values: &["audio", "video", "pdf", "notebook", "table", "iframe", "3d"],
                default: "",
                description: "v1 embed kind. Set on the embed element. Theme authors target `.moss-embed[data-type=...]`.",
            },
            DataAttr {
                name: "data-loop",
                values: &[],
                default: "",
                description: "Ambient background video: autoplay + muted + loop + playsinline, controls off. Authored as `![[clip.mp4|loop]]`. Boolean presence flag (value is empty). JS reads it to apply the reduced-motion guard and mount the pause/play toggle.",
            },
            DataAttr {
                name: "data-width",
                values: &["body", "wide", "page", "screen"],
                default: "body",
                description: "Display width — text-column (body), wider than text (wide), page-width (page), or viewport-width (screen). See spec § P9.",
            },
            DataAttr {
                name: "data-provider",
                values: &["youtube", "vimeo", "codepen"],
                default: "",
                description: "Identifies the embed provider for external URL embeds. Absent for generic iframes and local HTML embeds.",
            },
        ],
        example_html: r#"<video class="moss-embed moss-embed-video" data-type="video" data-loop src="clip.mp4" autoplay muted loop playsinline preload="metadata"></video>"#,
        example_markdown: "![[clip.mp4|loop]]",
        status: Status::Confirmed,
        since: "0",
        description: "Base class on every typed embed. Kind on `data-type` (v1). Ambient video: add `data-loop` via `![[clip.mp4|loop]]`. `.moss-embed-audio` / `-video` / `-pdf` / `-notebook` / `-table` / `-iframe` / `-3d` retired in Phase 1c.",
    },
    ComponentEntry {
        class: "moss-embed-audio",
        kind: "instance",
        parent: "moss-embed",
        data_attrs: &[],
        example_html: r#"<div class="moss-embed moss-embed-audio"><audio controls src="..."></audio></div>"#,
        example_markdown: "![[track.mp3]]",
        status: Status::Retired,
        since: "0",
        description: "Retired in Phase 1c — collapsed to `.moss-embed[data-type=audio]`.",
    },
    ComponentEntry {
        class: "moss-embed-video",
        kind: "instance",
        parent: "moss-embed",
        data_attrs: &[],
        example_html: r#"<div class="moss-embed moss-embed-video"><video controls src="..."></video></div>"#,
        example_markdown: "![[clip.mp4]]",
        status: Status::Retired,
        since: "0",
        description: "Retired in Phase 1c — collapsed to `.moss-embed[data-type=video]`.",
    },
    ComponentEntry {
        class: "moss-embed-pdf",
        kind: "instance",
        parent: "moss-embed",
        data_attrs: &[],
        example_html: r#"<div class="moss-embed moss-embed-pdf"><iframe src="..."></iframe></div>"#,
        example_markdown: "![[paper.pdf]]",
        status: Status::Retired,
        since: "0",
        description: "Retired in Phase 1c — collapsed to `.moss-embed[data-type=pdf]`.",
    },
    ComponentEntry {
        class: "moss-embed-iframe",
        kind: "instance",
        parent: "moss-embed",
        data_attrs: &[],
        example_html: r#"<div class="moss-embed moss-embed-iframe"><iframe src="..."></iframe></div>"#,
        example_markdown: "![[page.html]]",
        status: Status::Retired,
        since: "0",
        description: "Retired in Phase 1c — collapsed to `.moss-embed[data-type=iframe]`.",
    },
    ComponentEntry {
        class: "moss-embed-notebook",
        kind: "instance",
        parent: "moss-embed",
        data_attrs: &[],
        example_html: r#"<div class="moss-embed moss-embed-notebook">...</div>"#,
        example_markdown: "![[analysis.ipynb]]",
        status: Status::Retired,
        since: "0",
        description: "Retired in Phase 1c — collapsed to `.moss-embed[data-type=notebook]`.",
    },
    ComponentEntry {
        class: "moss-embed-ipynb",
        kind: "instance",
        parent: "moss-embed",
        data_attrs: &[],
        example_html: r#"<div class="moss-embed moss-embed-ipynb">...</div>"#,
        example_markdown: "",
        status: Status::Emerging,
        since: "0",
        description: "Alias of `.moss-embed-notebook`; consolidation pending.",
    },
    ComponentEntry {
        class: "moss-embed-table",
        kind: "instance",
        parent: "moss-embed",
        data_attrs: &[],
        example_html: r#"<div class="moss-embed moss-embed-table"><table>...</table></div>"#,
        example_markdown: "![[data.csv]]",
        status: Status::Retired,
        since: "0",
        description: "Retired in Phase 1c — collapsed to `.moss-embed[data-type=table]`.",
    },
    ComponentEntry {
        class: "moss-embed-3d",
        kind: "instance",
        parent: "moss-embed",
        data_attrs: &[],
        example_html: r#"<div class="moss-embed moss-embed-3d">...</div>"#,
        example_markdown: "![[model.glb]]",
        status: Status::Retired,
        since: "0",
        description: "Retired in Phase 1c — collapsed to `.moss-embed[data-type=3d]`.",
    },
    ComponentEntry {
        class: "moss-embed-error",
        kind: "instance",
        parent: "moss-embed",
        data_attrs: &[],
        example_html: r#"<div class="moss-embed moss-embed-error">File not found: ...</div>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "Error state for embeds whose target cannot be resolved.",
    },
    ComponentEntry {
        class: "moss-embed-missing",
        kind: "instance",
        parent: "moss-embed",
        data_attrs: &[],
        example_html: r#"<div class="moss-embed-missing">Folder not found: journal</div>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "1",
        description: "Fallback rendered when a folder-list embed (`![[journal/]]`) targets a folder that does not exist or cannot be resolved. Distinct from `.moss-embed-error` (file/wikilink resolution failure) — this one is specifically the folder-listing path.",
    },
    // -------------------------------------------------------------------
    // Hero, image, visual primitives.
    // -------------------------------------------------------------------
    ComponentEntry {
        class: "moss-hero",
        kind: "standalone",
        parent: "",
        data_attrs: &[
            DataAttr {
                name: "data-width",
                values: &["body", "wide", "page", "screen"],
                default: "body",
                description: "Display width — text-column (body), wider than text (wide), page-width (page), or viewport-width (screen). See spec § P9. Emitted from the authoring shortcode (e.g. `:::hero {full}` -> `data-width=\"screen\"`); on article children, site.css sizes the band via the content-width escape (ADR-021 Corollary 2). The hero itself escapes by DOM position (outside `<main>`), not by these rules.",
            },
            DataAttr {
                name: "data-slides",
                values: &["2", "3", "4", "5", "6"],
                default: "",
                description: "Slide count of a multi-image hero (consecutive leading media lines). Present only when > 1; drives the ambient CSS crossfade — one slide visible at a time, no controls. Absent = single-image hero, today's exact markup.",
            },
            DataAttr {
                name: "data-hero-tone",
                values: &["light"],
                default: "",
                description: "Marks a hero whose image is pale enough (scan-cached dominant colour above 0.4 relative luminance) that white overlay text cannot clear 4.5:1 over it. site.css responds by removing the legibility scrim and setting the overlay text DARK — a pale image needs no scrim to carry dark type, and darkening it hard enough to carry white type (this rule used to reach 0.78 black) greys out the picture the author chose. Applies to the two overlaid layouts; mobile-stacked text sits on `--moss-cover-color` and stays white. Emitted only when the hero also carries overlay text. Absent = mid-tone or dark image, no overlay, or an unparseable colour — all keep white type over the default ramp.",
            },
            DataAttr {
                name: "data-mobile",
                values: &["overlay"],
                default: "",
                description: "Below **48rem** (moss's mobile threshold), `overlay` keeps the title on top of the image instead of stacking it underneath. Emitted **only** for `:::hero {mobile=overlay}` — an author must ask for it; a hero with overlay text does not get it by default. The selector to fight if you want the other behaviour is `.moss-hero[data-mobile=\"overlay\"]`.",
            },
            DataAttr {
                name: "data-captioned",
                values: &[""],
                default: "",
                description: "Present when the hero carries `caption=\"…\"`. Such a hero is a photograph on display rather than a backdrop for overlay text, and a caption that names a subject is a promise the subject is in frame — so site.css shows the whole image instead of the default crop-to-fill: the box takes the picture's own shape, centred, bounded by `--moss-hero-max-height` rather than filling the frame. Put the crop back on the image itself (`image=cover.jpg|cover top`), which lands as an inline style and wins.",
            },
        ],
        example_html: r#"<section class="moss-hero" data-width="page">
  <div class="moss-hero-content">...</div>
</section>"#,
        example_markdown: ":::hero {image=cover.jpg}\n:::\n\n:::hero {image=cover.jpg full mobile=overlay}\n# Title over the image\n:::\n",
        status: Status::Confirmed,
        since: "0",
        description: "Hero banner section at the top of a page (cover image + title). v1 adds `data-width` for author-controlled sizing.",
    },
    ComponentEntry {
        class: "moss-hero-content",
        kind: "instance",
        parent: "moss-hero",
        data_attrs: &[],
        example_html: r#"<div class="moss-hero-content">...</div>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "Text content slot inside `.moss-hero` — text laid ON the image. For text ABOUT the image, see `.moss-hero-caption`.",
    },
    ComponentEntry {
        class: "moss-hero-caption",
        kind: "standalone",
        parent: "",
        data_attrs: &[],
        example_html: r#"<p class="moss-hero-caption">封面：基輔米迦勒修道院門口的陣亡將士紀念牆（拍攝：糜緒洋）</p>"#,
        example_markdown: ":::hero {image=cover.jpg caption=\"Cover: the memorial wall (photo: A. Photographer)\"}\n:::\n",
        status: Status::Confirmed,
        since: "0",
        description: "Caption or credit for a hero image, from `:::hero {caption=\"…\"}`. A SIBLING of `.moss-hero`, immediately after it — not a child: the section is a fixed-height cropping frame, and a photographer's credit has to survive as text below the picture rather than be printed across it. Rendered as inline markdown, so a credit can be a link, exactly like a `byline:` / `colophon:` row.",
    },
    ComponentEntry {
        class: "moss-hero-slides",
        kind: "instance",
        parent: "moss-hero",
        data_attrs: &[],
        example_html: r#"<div class="moss-hero-slides"><div class="moss-hero-slide"><img src="portrait-1.jpg" alt="" /></div></div>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "Wrapper holding the `.moss-hero-slide` images of a multi-image hero; the CSS ambient crossfade cycles one slide visible at a time.",
    },
    ComponentEntry {
        class: "moss-hero-slide",
        kind: "instance",
        parent: "moss-hero",
        data_attrs: &[],
        example_html: r#"<div class="moss-hero-slide"><img src="portrait-1.jpg" alt="" /></div>"#,
        example_markdown: ":::hero
![[portrait-1.jpg]]
![[portrait-2.jpg]]
# Title
:::
",
        status: Status::Confirmed,
        since: "0",
        description: "One background slide of a multi-image hero. Emitted only when the hero has 2+ images; slides crossfade ambiently via site.css keyed on the section's data-slides. First slide is the reduced-motion static fallback.",
    },
    ComponentEntry {
        class: "moss-image",
        kind: "standalone",
        parent: "",
        data_attrs: &[
            DataAttr {
                name: "data-aspect",
                values: &["portrait", "square", "auto"],
                default: "auto",
                description: "v1 image aspect-ratio hint. Theme authors target `.moss-image[data-aspect=...]`. Emitter wiring lands in a follow-up.",
            },
            DataAttr {
                name: "data-width",
                values: &["body", "wide", "page", "screen"],
                default: "body",
                description: "Display width — text-column (body), wider than text (wide), page-width (page), or viewport-width (screen). See spec § P9.",
            },
        ],
        example_html: r#"<figure class="moss-image" style="width:55%"><img src="..." alt="..." /></figure>"#,
        example_markdown: "![alt](image.jpg)",
        status: Status::Confirmed,
        since: "0",
        description: "Wrapper around an inline `<img>` for sizing and figure semantics. `data-width` carries a named width token (body|wide|page|screen); a content-relative width is instead emitted as inline `style=\"width:NN%\"` (set by the editor drag-resize), which also forces the inner image to fill that percent box. Images narrower than the content column center horizontally.",
    },
    ComponentEntry {
        class: "moss-align-left",
        kind: "standalone",
        parent: "",
        data_attrs: &[],
        example_html: r#"<img src="..." alt="..." class="moss-align-left" />"#,
        example_markdown: "![[photo.jpg|align-left]]",
        status: Status::Confirmed,
        since: "0",
        description: "Floats an image to the left of body text (editorial runaround). Defaults max-width to 50% on desktop, collapses to full-width below 48rem. CSS `:has()` escalates the float to a wrapping `<figure class=\"moss-image\">` or `<picture>` when present. Mirrors WordPress's `alignleft` convention.",
    },
    ComponentEntry {
        class: "moss-align-right",
        kind: "standalone",
        parent: "",
        data_attrs: &[],
        example_html: r#"<img src="..." alt="..." class="moss-align-right" />"#,
        example_markdown: "![[photo.jpg|align-right]]",
        status: Status::Confirmed,
        since: "0",
        description: "Floats an image to the right of body text (editorial runaround). Symmetric counterpart to `.moss-align-left`. Mirrors WordPress's `alignright` convention.",
    },
    ComponentEntry {
        class: "moss-article-title",
        kind: "instance",
        parent: "",
        data_attrs: &[],
        example_html: r#"<h1 class="moss-article-title">Title</h1>"#,
        example_markdown: "",
        status: Status::Emerging,
        since: "0",
        description: "Article-page H1 title emitted from frontmatter.",
    },
    ComponentEntry {
        class: "moss-heading-anchor",
        kind: "instance",
        parent: "",
        data_attrs: &[],
        example_html: r##"<h2 id="setup">Setup<a class="moss-heading-anchor" href="#setup" aria-label="Permalink to this section"></a></h2>"##,
        example_markdown: "## Setup",
        status: Status::Emerging,
        since: "1",
        description: "Clickable permalink appended inside every author-written body heading that carries a slug id; links to the heading's `#`-fragment. The element is EMPTY — the `#` a reader sees is drawn by `site.css` as `::after` content, so selecting a heading never copies it. Not emitted for a display title: the auto-injected `moss-article-title` H1, a `:::hero` overlay heading, and a `:::grid` cell heading all get none.",
    },
    // -------------------------------------------------------------------
    // Grid + gallery + buttons containers (free-form layouts).
    // -------------------------------------------------------------------
    ComponentEntry {
        class: "moss-grid",
        kind: "container",
        parent: "",
        data_attrs: &[
            DataAttr {
                name: "data-width",
                values: &["body", "wide", "page", "screen"],
                default: "body",
                description: "Display width — text-column (body), wider than text (wide), page-width (page), or viewport-width (screen). See spec § P9.",
            },
            DataAttr {
                name: "data-columns",
                values: &["1", "2", "3", "4"],
                default: "",
                description: "Column count, from `:::grid N`. Note the responsive default: below 768px moss collapses `[data-columns]` to a single column, which is right for a grid of cards and wrong for a grid of short text lines. Re-assert `grid-template-columns` inside your own media query if yours is the latter. A ratio (`:::grid 2 1:2`) arrives as the custom property `--moss-grid-ratio` on the element, so it stays overridable — the collapse applies to ratio grids too.",
            },
        ],
        example_html: r#"<div class="moss-grid" data-width="wide">
  <div class="moss-grid-card">...</div>
</div>"#,
        example_markdown: ":::grid {cols=2}\nLeft cell\n+++\nRight cell\n:::\n",
        status: Status::Confirmed,
        since: "0",
        description: "Generic grid container (used by profiles, link previews, etc.). Modifier classes: `profiles`, `featured`, `no-cards`. v1 adds `data-width` (P9).",
    },
    ComponentEntry {
        class: "moss-grid-card",
        kind: "instance",
        parent: "moss-grid",
        data_attrs: &[
            DataAttr {
                name: "data-kind",
                values: &["link", "friend", "card"],
                default: "card",
                description: "v1 grid-card variant. Today expressed via co-emitted classes (`.link-card`, `.friend-card`, `.no-cards`); Phase 1c collapses to this `data-kind` attribute.",
            },
            DataAttr {
                name: "data-cover-color",
                values: &[],
                default: "",
                description: "Presence flag: emitted IFF the cell's first block is an image, alone in a paragraph or in a figure. The image's dominant colour arrives alongside it as `--moss-cover-color` in the element's `style`. moss paints nothing with it — the attribute exists so a theme can give a hand-built cell (cover, then the author's own text) the same colour band a collection card gets.",
            },
        ],
        example_html: r#"<a class="moss-grid-card" data-kind="link" href="...">...</a>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "Card instance inside `.moss-grid`. Today emits sibling classes `link-card` / `friend-card` / `no-cards`; v1 collapses to `data-kind`.",
    },
    ComponentEntry {
        class: "moss-gallery",
        kind: "container",
        parent: "",
        data_attrs: &[
            DataAttr {
                name: "data-width",
                values: &["body", "wide", "page", "screen"],
                default: "body",
                description: "Display width — text-column (body), wider than text (wide), page-width (page), or viewport-width (screen). See spec § P9.",
            },
            DataAttr {
                name: "data-columns",
                values: &[],
                default: "",
                description: "Column count, from `:::gallery N` — the author names it rather than moss inferring it. The **opposite** of `.moss-grid[data-columns]` on mobile: below 48rem the grid collapses to one column, while the gallery uses `auto-fill` to keep as many tracks as clear 88px. N becomes a maximum rather than a mandate, and a gallery that already fits stays at its authored count. Collapsing a wall of thumbnails to one column is wrong; collapsing prose cells is right.",
            },
        ],
        example_html: r#"<div class="moss-gallery" data-width="page">
  <div class="moss-gallery-item">...</div>
</div>"#,
        example_markdown: ":::gallery\nphoto.jpg\n:::\n",
        status: Status::Confirmed,
        since: "0",
        description: "Image gallery container. v1 adds `data-width` (P9).",
    },
    ComponentEntry {
        class: "moss-gallery-item",
        kind: "instance",
        parent: "moss-gallery",
        data_attrs: &[],
        example_html: r#"<div class="moss-gallery-item"><img src="..." /></div>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "Single image entry inside `.moss-gallery`.",
    },
    ComponentEntry {
        class: "moss-buttons",
        kind: "container",
        parent: "",
        data_attrs: &[
            DataAttr {
                name: "data-style",
                values: &["default", "inverted"],
                default: "default",
                description: "v1 button-row style. Theme authors target `.moss-buttons[data-style=...]`.",
            },
        ],
        example_html: r#"<div class="moss-buttons" data-style="inverted">
  <a class="moss-btn" href="...">Click</a>
</div>"#,
        example_markdown: ":::buttons\n[Get started](https://example.com)\n:::\n",
        status: Status::Confirmed,
        since: "0",
        description: "Container for a row of `.moss-btn` buttons. v1: the inverted variant is on `data-style=\"inverted\"`.",
    },
    // -------------------------------------------------------------------
    // Button primitive (used by subscribe + general CTAs).
    // -------------------------------------------------------------------
    ComponentEntry {
        class: "moss-btn",
        kind: "standalone",
        parent: "",
        data_attrs: &[
            DataAttr {
                name: "data-role",
                values: &["default", "primary", "secondary"],
                default: "default",
                description: "v1 button role. Theme authors target `.moss-btn[data-role=...]`.",
            },
        ],
        example_html: r#"<button class="moss-btn" data-role="primary">
  <span class="moss-btn__label">Submit</span>
</button>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "Generic button primitive. Role on `data-role` (v1).",
    },
    ComponentEntry {
        class: "moss-btn__label",
        kind: "instance",
        parent: "moss-btn",
        data_attrs: &[],
        example_html: r#"<span class="moss-btn__label">Submit</span>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "Label span inside `.moss-btn`.",
    },
    ComponentEntry {
        class: "moss-btn__check",
        kind: "instance",
        parent: "moss-btn",
        data_attrs: &[],
        example_html: r#"<span class="moss-btn__check">✓</span>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "Success checkmark slot inside `.moss-btn`.",
    },
    ComponentEntry {
        class: "moss-btn__spinner",
        kind: "instance",
        parent: "moss-btn",
        data_attrs: &[],
        example_html: r#"<span class="moss-btn__spinner"></span>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "Loading spinner slot inside `.moss-btn`.",
    },
    // -------------------------------------------------------------------
    // Subscribe form (newsletter / Buttondown / seta).
    // -------------------------------------------------------------------
    ComponentEntry {
        class: "moss-subscribe",
        kind: "standalone",
        parent: "",
        data_attrs: &[],
        example_html: r#"<div class="moss-subscribe">
  <form class="moss-subscribe-form">...</form>
</div>"#,
        example_markdown: ":::subscribe\n:::\n",
        status: Status::Confirmed,
        since: "0",
        description: "Newsletter subscribe block (auto-injected into footer when email channel configured).",
    },
    ComponentEntry {
        class: "moss-subscribe-form",
        kind: "instance",
        parent: "moss-subscribe",
        data_attrs: &[
            DataAttr {
                name: "data-position",
                values: &["inline", "apply"],
                default: "inline",
                description: "Placement/behavior variant. All moss-hosted subscribe forms are `inline` (the auto-injected footer form and the `:::subscribe` shortcode emit identical HTML — footer vs in-page styling keys on the `footer` ancestor in CSS, not this attribute). `apply` marks the `:::apply` form (terminal success, FormData body).",
            },
            DataAttr {
                name: "data-button-override",
                values: &["true"],
                default: "true",
                description: "Emitted only when the author overrides the button label (`:::subscribe{button=\"...\"}`). Signals subscribe.ts to leave the button label AND placeholder as authored instead of overwriting them with the language-default copy.",
            },
            DataAttr {
                name: "data-moss-hosted",
                values: &["true"],
                default: "true",
                description: "Marks moss-hosted (seta) forms hydrated by subscribe.ts. Absent on 3rd-party provider forms.",
            },
            DataAttr {
                name: "data-state",
                values: &["idle", "loading", "success", "error"],
                default: "idle",
                description: "Runtime submit state machine, driven by subscribe.ts. Emitted as `idle`; theme authors target `.moss-subscribe-form[data-state=...]`.",
            },
            DataAttr {
                name: "data-moss-pending-site",
                values: &["true"],
                default: "true",
                description: "Pre-first-publish pending wiring (`action=\"#\"`, no site_id yet). Hidden on published pages (body without `data-moss-preview`) via the email.css defense rule so a pending form never faces real readers.",
            },
        ],
        example_html: r#"<form class="moss-subscribe-form">...</form>"#,
        example_markdown: "",
        status: Status::Emerging,
        since: "0",
        description: "Form element inside `.moss-subscribe`.",
    },
    ComponentEntry {
        class: "moss-btn-slot",
        kind: "instance",
        parent: "moss-subscribe",
        data_attrs: &[],
        example_html: r#"<div class="moss-btn-slot"><button class="moss-btn">...</button></div>"#,
        example_markdown: "",
        status: Status::Emerging,
        since: "0",
        description: "Fixed-width slot wrapping a form's submit button; used by both the subscribe and comment forms to prevent layout shift across idle/loading/success states.",
    },
    ComponentEntry {
        class: "moss-subscribe-status",
        kind: "instance",
        parent: "moss-subscribe",
        data_attrs: &[],
        example_html: r#"<div class="moss-subscribe-status">
  <span class="moss-subscribe-status__icon"></span>
  Subscribed!
</div>"#,
        example_markdown: "",
        status: Status::Emerging,
        since: "0",
        description: "Status message shown after submit (success/error).",
    },
    ComponentEntry {
        class: "moss-subscribe-status__icon",
        kind: "instance",
        parent: "moss-subscribe-status",
        data_attrs: &[],
        example_html: r#"<span class="moss-subscribe-status__icon"></span>"#,
        example_markdown: "",
        status: Status::Emerging,
        since: "0",
        description: "Icon slot inside `.moss-subscribe-status`.",
    },
    ComponentEntry {
        class: "moss-subscribe-landing",
        kind: "standalone",
        parent: "",
        data_attrs: &[],
        example_html: r#"<section class="moss-subscribe-landing">...</section>"#,
        example_markdown: "",
        status: Status::Emerging,
        since: "0",
        description: "Standalone subscribe landing page surface (larger variant).",
    },
    // -------------------------------------------------------------------
    // Apply form (membership / contributor application).
    // -------------------------------------------------------------------
    ComponentEntry {
        class: "moss-apply",
        kind: "standalone",
        parent: "",
        data_attrs: &[],
        example_html: r#"<div class="moss-apply" data-state="idle">
  <form class="moss-subscribe-form moss-apply-form">...</form>
</div>"#,
        example_markdown: ":::apply\n:::\n",
        status: Status::Emerging,
        since: "0",
        description: "Apply / membership-request form block (:::apply shortcode).",
    },
    ComponentEntry {
        class: "moss-apply-form",
        kind: "instance",
        parent: "moss-apply",
        data_attrs: &[
            DataAttr {
                name: "data-position",
                values: &["apply"],
                default: "apply",
                description: "Position variant; always `apply` for this form. Drives CSS layout in email.css.",
            },
            DataAttr {
                name: "data-revert",
                values: &["false"],
                default: "false",
                description: "When `false`, success is terminal (no auto-revert). subscribe.ts reads this.",
            },
        ],
        example_html: r#"<form class="moss-subscribe-form moss-apply-form" data-position="apply" data-revert="false">...</form>"#,
        example_markdown: "",
        status: Status::Emerging,
        since: "0",
        description: "Form element inside `.moss-apply`. Also carries `.moss-subscribe-form` so subscribe.ts hydrates it.",
    },
    ComponentEntry {
        class: "moss-apply-matters",
        kind: "instance",
        parent: "moss-apply",
        data_attrs: &[],
        example_html: r#"<input type="text" name="matters" class="moss-input moss-apply-matters">"#,
        example_markdown: "",
        status: Status::Emerging,
        since: "0",
        description: "Second apply-form input inside `.moss-apply-form` — a Matters username OR a one-line pitch (placeholder-only, no visible label).",
    },
    ComponentEntry {
        class: "moss-apply-hp",
        kind: "instance",
        parent: "moss-apply",
        data_attrs: &[],
        example_html: r#"<input type="text" name="website" class="moss-apply-hp" tabindex="-1" aria-hidden="true">"#,
        example_markdown: "",
        status: Status::Emerging,
        since: "0",
        description: "Honeypot field (off-screen) inside `.moss-apply-form`. Bots fill it; humans don't.",
    },
    ComponentEntry {
        class: "moss-apply-status",
        kind: "instance",
        parent: "moss-apply",
        data_attrs: &[],
        example_html: r#"<div class="moss-subscribe-status moss-apply-status" aria-live="polite">...</div>"#,
        example_markdown: "",
        status: Status::Emerging,
        since: "0",
        description: "Status region inside `.moss-apply-form` (also carries `.moss-subscribe-status`).",
    },
    ComponentEntry {
        class: "moss-apply-helper",
        kind: "instance",
        parent: "moss-apply",
        data_attrs: &[],
        example_html: r#"<p class="moss-apply-helper" id="moss-apply-email-help">用于获取邀请及免费托管服务</p>"#,
        example_markdown: "",
        status: Status::Emerging,
        since: "0",
        description: "Helper text line beneath each field in `.moss-apply-form` (referenced by the field's aria-describedby). Internal — not part of the public component contract.",
    },
    // -------------------------------------------------------------------
    // Series navigation (prev/next + collection links).
    // -------------------------------------------------------------------
    ComponentEntry {
        class: "moss-series-nav",
        kind: "standalone",
        parent: "",
        data_attrs: &[],
        example_html: r#"<nav class="moss-series-nav">
  <div class="moss-series-nav-links">...</div>
</nav>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "Series navigation bar (prev/next/collection) on series pages.",
    },
    ComponentEntry {
        class: "moss-series-nav-links",
        kind: "instance",
        parent: "moss-series-nav",
        data_attrs: &[],
        example_html: r#"<div class="moss-series-nav-links">...</div>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "Row holding prev/next links in series nav.",
    },
    ComponentEntry {
        class: "moss-series-nav-link",
        kind: "instance",
        parent: "moss-series-nav",
        data_attrs: &[],
        example_html: r#"<a class="moss-series-nav-link moss-series-nav-prev" href="...">...</a>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "Individual link inside series nav. Modifiers: `moss-series-nav-prev`, `moss-series-nav-next`, `empty` (placeholder).",
    },
    ComponentEntry {
        class: "moss-series-nav-prev",
        kind: "instance",
        parent: "moss-series-nav",
        data_attrs: &[],
        example_html: r#"<a class="moss-series-nav-link moss-series-nav-prev" href="...">...</a>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "Previous-page modifier on a series nav link.",
    },
    ComponentEntry {
        class: "moss-series-nav-next",
        kind: "instance",
        parent: "moss-series-nav",
        data_attrs: &[],
        example_html: r#"<a class="moss-series-nav-link moss-series-nav-next" href="...">...</a>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "Next-page modifier on a series nav link.",
    },
    ComponentEntry {
        class: "moss-series-nav-arrow",
        kind: "instance",
        parent: "moss-series-nav",
        data_attrs: &[],
        example_html: r#"<span class="moss-series-nav-arrow">→</span>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "Arrow glyph inside a series-nav link.",
    },
    ComponentEntry {
        class: "moss-series-nav-title",
        kind: "instance",
        parent: "moss-series-nav",
        data_attrs: &[],
        example_html: r#"<span class="moss-series-nav-title">Next page title</span>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "Title text of the destination page in a series-nav link.",
    },
    ComponentEntry {
        class: "moss-series-nav-collection",
        kind: "instance",
        parent: "moss-series-nav",
        data_attrs: &[],
        example_html: r#"<div class="moss-series-nav-collection">...</div>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "Collection-listing slot in series nav (sibling pages).",
    },
    ComponentEntry {
        class: "moss-series-nav-collection-row",
        kind: "instance",
        parent: "moss-series-nav-collection",
        data_attrs: &[],
        example_html: r#"<div class="moss-series-nav-collection-row">...</div>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "Row inside the collection listing of series nav.",
    },
    ComponentEntry {
        class: "moss-series-nav-position",
        kind: "instance",
        parent: "moss-series-nav-collection-row",
        data_attrs: &[],
        example_html: r#"<span class="moss-series-nav-position">2 of 3</span>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "Where this page sits in its series — \"2 of 3\" / 「第 2 篇，共 3 篇」. Counts only the pages still in the reading order, so a page that stepped out with `series: false` is not in the total. Omitted when the folder holds a single page.",
    },
    // -------------------------------------------------------------------
    // Collection cover (collection landing pages).
    // -------------------------------------------------------------------
    ComponentEntry {
        class: "moss-collection-cover",
        kind: "standalone",
        parent: "",
        data_attrs: &[],
        example_html: r#"<section class="moss-collection-cover">
  <div class="moss-collection-cover-row">...</div>
</section>"#,
        example_markdown: "",
        status: Status::Emerging,
        since: "0",
        description: "Header surface on a collection landing page.",
    },
    ComponentEntry {
        class: "moss-collection-cover-row",
        kind: "instance",
        parent: "moss-collection-cover",
        data_attrs: &[],
        example_html: r#"<div class="moss-collection-cover-row">...</div>"#,
        example_markdown: "",
        status: Status::Emerging,
        since: "0",
        description: "Row inside `.moss-collection-cover`.",
    },
    ComponentEntry {
        class: "moss-collection-cover-body",
        kind: "instance",
        parent: "moss-collection-cover",
        data_attrs: &[],
        example_html: r#"<div class="moss-collection-cover-body">...</div>"#,
        example_markdown: "",
        status: Status::Emerging,
        since: "0",
        description: "Body content slot inside `.moss-collection-cover`.",
    },
    // -------------------------------------------------------------------
    // Form primitives (input, label, field, link).
    // -------------------------------------------------------------------
    ComponentEntry {
        class: "moss-input",
        kind: "standalone",
        parent: "",
        data_attrs: &[],
        example_html: r#"<input class="moss-input" type="email" />"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "Generic form input primitive.",
    },
    ComponentEntry {
        class: "moss-field",
        kind: "container",
        parent: "",
        data_attrs: &[],
        example_html: r#"<div class="moss-field">
  <label class="moss-label">Email</label>
  <input class="moss-input" />
</div>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "Form field group (label + input). Modifier `--inline` for horizontal layout.",
    },
    ComponentEntry {
        class: "moss-label",
        kind: "instance",
        parent: "moss-field",
        data_attrs: &[],
        example_html: r#"<label class="moss-label">Email</label>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "Label primitive for `.moss-field`. Modifier `--small` for compact form.",
    },
    ComponentEntry {
        class: "moss-link",
        kind: "standalone",
        parent: "",
        data_attrs: &[],
        example_html: r#"<a class="moss-link" href="...">Click me</a>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "Inline-link primitive (resets `<button>` chrome too). Use `--subtle` for muted variant.",
    },
    ComponentEntry {
        class: "moss-field--inline",
        kind: "instance",
        parent: "moss-field",
        data_attrs: &[],
        example_html: r#"<div class="moss-field moss-field--inline">
  <label class="moss-label">Email</label>
  <input class="moss-input" />
</div>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "BEM modifier on `.moss-field` for horizontal label+input layout (used by settings UI primitives).",
    },
    ComponentEntry {
        class: "moss-label--small",
        kind: "instance",
        parent: "moss-label",
        data_attrs: &[],
        example_html: r#"<label class="moss-label moss-label--small">Compact label</label>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "BEM modifier on `.moss-label` for compact form (used by services settings rows).",
    },
    ComponentEntry {
        class: "moss-info-grid",
        kind: "container",
        parent: "",
        data_attrs: &[],
        example_html: r#"<div class="moss-info-grid">
  <div class="moss-field moss-field--inline">...</div>
  <div class="moss-field moss-field--inline">...</div>
</div>"#,
        example_markdown: "",
        status: Status::Emerging,
        since: "0",
        description: "Two-column aligned label+value rows (CSS grid with `display: contents` children). Used by the deployment settings panel; ships in the default theme so authors can reuse the layout.",
    },
    ComponentEntry {
        class: "moss-row",
        kind: "container",
        parent: "",
        data_attrs: &[],
        example_html: r#"<div class="moss-row">
  <div class="moss-field">...</div>
  <div class="moss-field">...</div>
</div>"#,
        example_markdown: "",
        status: Status::Emerging,
        since: "0",
        description: "Horizontal flex row of equal-flex `.moss-field` children. Form-row layout helper shipped in the default theme.",
    },
    ComponentEntry {
        class: "moss-input-feedback",
        kind: "instance",
        parent: "moss-field",
        data_attrs: &[],
        example_html: r#"<span class="moss-input-feedback">Saving…</span>"#,
        example_markdown: "",
        status: Status::Emerging,
        since: "0",
        description: "Auto-save status hint slot under `.moss-field`. Three state modifiers: `--success`, `--error`, `--fade-out`.",
    },
    ComponentEntry {
        class: "moss-input-feedback--success",
        kind: "instance",
        parent: "moss-input-feedback",
        data_attrs: &[],
        example_html: r#"<span class="moss-input-feedback moss-input-feedback--success">Saved</span>"#,
        example_markdown: "",
        status: Status::Emerging,
        since: "0",
        description: "Success state modifier on `.moss-input-feedback`.",
    },
    ComponentEntry {
        class: "moss-input-feedback--error",
        kind: "instance",
        parent: "moss-input-feedback",
        data_attrs: &[],
        example_html: r#"<span class="moss-input-feedback moss-input-feedback--error">Failed to save</span>"#,
        example_markdown: "",
        status: Status::Emerging,
        since: "0",
        description: "Error state modifier on `.moss-input-feedback`.",
    },
    ComponentEntry {
        class: "moss-input-feedback--fade-out",
        kind: "instance",
        parent: "moss-input-feedback",
        data_attrs: &[],
        example_html: r#"<span class="moss-input-feedback moss-input-feedback--success moss-input-feedback--fade-out">Saved</span>"#,
        example_markdown: "",
        status: Status::Emerging,
        since: "0",
        description: "Transient fade-out modifier on `.moss-input-feedback` (applied after a success message to dismiss it).",
    },
    // -------------------------------------------------------------------
    // Other emit surfaces (comments, colophon, shell frame, misc).
    // -------------------------------------------------------------------
    ComponentEntry {
        class: "moss-comments",
        kind: "standalone",
        parent: "",
        data_attrs: &[],
        example_html: r#"<section class="moss-comments">...</section>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "Comments surface (per-site SQLite backend or Artalk legacy).",
    },
    ComponentEntry {
        class: "moss-service-inactive",
        kind: "instance",
        parent: "",
        data_attrs: &[],
        example_html: r#"<section class="moss-comments moss-service-inactive">...</section>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "Co-class applied to `.moss-comments` and `.moss-subscribe-form` when the backing service is not configured. Hidden by default in published sites and revealed inside the preview chrome so authors can see the inactive surface during editing.",
    },
    // -------------------------------------------------------------------
    // Preview link popover — emitted by `assets/js/preview.js` runtime.
    // -------------------------------------------------------------------
    ComponentEntry {
        class: "moss-preview-popup",
        kind: "chrome",
        parent: "",
        data_attrs: &[],
        example_html: r#"<div class="moss-preview-popup" role="tooltip" aria-live="polite">
  <strong class="moss-preview-title">...</strong>
  <p class="moss-preview-desc">...</p>
  <p class="moss-preview-text">...</p>
</div>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "Floating link-preview popover injected at `document.body` level by the runtime `preview.js`. Fetches `/_moss/previews.json` and renders a hover card with title, description, and excerpt for internal links.",
    },
    ComponentEntry {
        class: "moss-preview-title",
        kind: "instance",
        parent: "moss-preview-popup",
        data_attrs: &[],
        example_html: r#"<strong class="moss-preview-title">Article title</strong>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "Title slot inside `.moss-preview-popup`.",
    },
    ComponentEntry {
        class: "moss-preview-desc",
        kind: "instance",
        parent: "moss-preview-popup",
        data_attrs: &[],
        example_html: r#"<p class="moss-preview-desc">Short description</p>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "Description slot inside `.moss-preview-popup` (from frontmatter `description`).",
    },
    ComponentEntry {
        class: "moss-preview-text",
        kind: "instance",
        parent: "moss-preview-popup",
        data_attrs: &[],
        example_html: r#"<p class="moss-preview-text">Excerpt of the linked article…</p>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "Excerpt slot inside `.moss-preview-popup` (auto-extracted from the linked article body).",
    },
    ComponentEntry {
        class: "moss-colophon",
        kind: "chrome",
        parent: "",
        data_attrs: &[],
        example_html: r#"<div class="moss-colophon">
  <a href="https://mosspub.com">
    <svg class="moss-colophon-icon"></svg>
    <span class="moss-colophon-label">Published with moss</span>
  </a>
</div>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "Footer colophon credit appended by moss. Shows the moss mark alone at rest; the wording fades in beneath it on hover or keyboard focus, without moving the mark.",
    },
    ComponentEntry {
        class: "moss-colophon-icon",
        kind: "instance",
        parent: "moss-colophon",
        data_attrs: &[],
        example_html: r#"<svg class="moss-colophon-icon"></svg>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "The moss mark inside `.moss-colophon`. Decorative (`aria-hidden`) — `.moss-colophon-label` carries the accessible name.",
    },
    ComponentEntry {
        class: "moss-colophon-label",
        kind: "instance",
        parent: "moss-colophon",
        data_attrs: &[],
        example_html: r#"<span class="moss-colophon-label">Published with moss</span>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "Localized attribution wording inside `.moss-colophon`. Transparent at rest and faded in on hover/focus, positioned out of flow beneath the mark so the reveal shifts nothing — it stays in the DOM because it is the link's accessible name.",
    },
    ComponentEntry {
        class: "moss-shell-frame",
        kind: "chrome",
        parent: "",
        data_attrs: &[],
        example_html: r#"<div class="moss-shell-frame">...</div>"#,
        example_markdown: "",
        status: Status::Emerging,
        since: "0",
        description: "App-shell frame surface (preview chrome).",
    },
    ComponentEntry {
        class: "moss-mobile-frame",
        kind: "chrome",
        parent: "moss-shell-frame",
        data_attrs: &[],
        example_html: r#"<html class="moss-shell-frame moss-mobile-frame">...</html>"#,
        example_markdown: "",
        status: Status::Emerging,
        since: "0",
        description: "Runtime marker the preview bridge adds to `<html>` when the shell is in mobile device-preview mode. Since ADR-039 the shell owns chrome clearance by insetting the preview iframe, so no CSS keys off this class and it currently has no effect; it is retained as a revert path and may be removed.",
    },
    ComponentEntry {
        class: "main-nav",
        kind: "chrome",
        parent: "",
        data_attrs: &[],
        example_html: r#"<nav class="main-nav container">...</nav>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "Top site navigation bar. Legacy non-`moss-` prefix kept for theme parity.",
    },
    // The article masthead and nav interior. Legacy non-`moss-` prefixes, kept
    // for theme parity like `main-nav` above.
    //
    // These were emitted but undeclared until 2026-08-05, and the omission had
    // a measured cost: an agent restyling a journalism site reaches for the
    // byline row first, found nothing for it in `describe --json`, and had to
    // recover the class by reading built HTML — which the shipped guidance
    // sanctions only as a self-check, and which silently breaks on a rename.
    // Declaring them is what makes "never hardcode a class from memory"
    // followable for the masthead. `components_sync_test` cannot guard these:
    // it only matches `class="moss-..."` literals.
    ComponentEntry {
        class: "date-line",
        kind: "chrome",
        parent: "",
        data_attrs: &[],
        example_html: r#"<div class="date-line"><span class="date">March 3, 2026</span><div class="font-anchor">...</div></div>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "Byline row under an article title: the publication date on the left, the reading-size control on the right. Emitted only when the page has a `date`.",
    },
    ComponentEntry {
        class: "date",
        kind: "instance",
        parent: "date-line",
        data_attrs: &[],
        example_html: r#"<span class="date">March 3, 2026</span>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "The formatted publication date inside `.date-line`. Text is localized to the page's language.",
    },
    ComponentEntry {
        class: "moss-byline",
        kind: "container",
        parent: "",
        data_attrs: &[],
        example_html: r#"<div class="moss-byline"><div class="moss-byline-row">作者　糜緒洋</div><div class="moss-byline-row">編輯　謝丁</div></div>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "1",
        description: "Credit block under the page title, below `.date-line` when there is one. Emitted from the `byline` frontmatter field on every page kind — articles, folder indexes, the homepage and plain pages alike — one `.moss-byline-row` per authored line. On a page moss gives no title of its own (the homepage, a `home: true` folder page, a plain page) it sits under the author's own opening `<h1>`, or at the top of the page content when the body has none. Absent when the field is.",
    },
    ComponentEntry {
        class: "moss-byline-row",
        kind: "instance",
        parent: "moss-byline",
        data_attrs: &[],
        example_html: r#"<div class="moss-byline-row">首發媒體　<a href="https://theinitium.com/a">端傳媒</a></div>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "1",
        description: "One credit line. Its content is the author's text rendered as inline markdown, so a row may contain links or emphasis. moss does not know which part is a role and which is a name — style the whole row.",
    },
    ComponentEntry {
        class: "moss-article-colophon",
        kind: "container",
        parent: "",
        data_attrs: &[],
        example_html: r#"<div class="moss-article-colophon"><div class="moss-article-colophon-row">首發媒體　<a href="https://theinitium.com/a">端傳媒</a></div></div>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "1",
        description: "Credit block at the FOOT of the page, emitted from the `colophon` frontmatter field — where the piece first ran, contributor biographies, production credits. Same rows as `.moss-byline`, different end of the page. Emitted on every page kind: inside `<article>` on an article page, and last in the page content everywhere else — after the children listing on a folder index or the homepage — where the enclosing element is not an `<article>` despite the class name. Unrelated to `.review-colophon`, which is the review feature's book card.",
    },
    ComponentEntry {
        class: "moss-article-colophon-row",
        kind: "instance",
        parent: "moss-article-colophon",
        data_attrs: &[],
        example_html: r#"<div class="moss-article-colophon-row">封面　基輔米迦勒修道院門口的陣亡將士紀念牆（拍攝：糜緒洋）</div>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "1",
        description: "One foot-credit line, rendered as inline markdown exactly like `.moss-byline-row`.",
    },
    ComponentEntry {
        class: "site-name",
        kind: "instance",
        parent: "main-nav",
        data_attrs: &[],
        example_html: r#"<a href="/" class="site-name">在場</a>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "The site title link at the left of the nav bar. On a non-home page the same slot may instead carry `.breadcrumb-segment`.",
    },
    ComponentEntry {
        class: "breadcrumb-segment",
        kind: "instance",
        parent: "main-nav",
        data_attrs: &[],
        example_html: r#"<a href="/awards/" class="breadcrumb-segment">獎項</a>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "One ancestor link in the nav-left breadcrumb trail, used in place of `.site-name` once the page is below the site root.",
    },
    ComponentEntry {
        class: "nav-icons",
        kind: "chrome",
        parent: "main-nav",
        data_attrs: &[],
        example_html: r#"<div class="nav-icons">...</div>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "Right-hand icon cluster in the nav bar (search, theme toggle, and similar). Stationary chrome, present whether or not the site has nav links.",
    },
    // The rest of the nav interior and the default footer, on the same footing
    // as the masthead block above: emitted since 0, styled in `site.css`, and
    // undeclared until 2026-08-05.
    //
    // The 2026-08-05 trial found the concrete cost. An agent asked to restyle a
    // site went looking in `describe --json` for the language switcher, found
    // nothing, and recovered `.nav-lang-toggle` by grepping built HTML — the one
    // move the shipped guidance tells agents not to make, because it breaks
    // silently on a rename. `main-nav`, `.site-name` and `.nav-icons` were
    // declared; everything they contain was not, which is the worst of both
    // (the contract looks complete enough to trust).
    ComponentEntry {
        class: "nav-left",
        kind: "chrome",
        parent: "main-nav",
        data_attrs: &[],
        example_html: r#"<div class="nav-left"><a href="/" class="site-name">在場</a></div>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "Left group of the nav bar. Holds either `.site-name` or the breadcrumb trail, never both.",
    },
    ComponentEntry {
        class: "nav-right",
        kind: "chrome",
        parent: "main-nav",
        data_attrs: &[],
        example_html: r#"<div class="nav-right">…hamburger, .nav-links, .nav-icons…</div>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "Right group of the nav bar: the mobile menu button, the nav links, and the icon cluster, in that order.",
    },
    ComponentEntry {
        class: "nav-links",
        kind: "chrome",
        parent: "nav-right",
        data_attrs: &[],
        example_html: r#"<div class="nav-links"><a href="/about/" class="active">關於</a>…</div>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "The nav link list. The link for the page currently being viewed additionally carries the bare class `active` — style `.nav-links .active`, not a `moss-` class.",
    },
    ComponentEntry {
        class: "site-logo",
        kind: "instance",
        parent: "site-name",
        data_attrs: &[],
        example_html: r#"<img class="site-logo" src="…" alt="" aria-hidden="true">"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "Optional logo image inside the site-name link. Decorative by construction (`alt=\"\"` + `aria-hidden`), because the adjacent text already names the site.",
    },
    ComponentEntry {
        class: "breadcrumb-label",
        kind: "instance",
        parent: "nav-left",
        data_attrs: &[],
        example_html: r#"<span class="breadcrumb-label">獎項</span>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "The final, non-linked breadcrumb segment — the page you are on. `.breadcrumb-segment` is the linked form for ancestors.",
    },
    ComponentEntry {
        class: "breadcrumb-separator",
        kind: "instance",
        parent: "nav-left",
        data_attrs: &[],
        example_html: r#"<span class="breadcrumb-separator">/</span>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "The `/` between breadcrumb segments. Restyle or hide this rather than trying to remove it from the markup.",
    },
    ComponentEntry {
        class: "mobile-menu-button",
        kind: "chrome",
        parent: "nav-right",
        data_attrs: &[],
        example_html: r#"<button class="mobile-menu-button" aria-label="…"><svg>…</svg></button>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "The hamburger. Emitted on every page and hidden by media query above the mobile breakpoint — it is not conditionally rendered, so a rule that shows it always will.",
    },
    ComponentEntry {
        class: "nav-search-btn",
        kind: "instance",
        parent: "nav-icons",
        data_attrs: &[],
        example_html: r#"<button class="nav-search-btn" type="button" aria-label="…"><svg class="search-icon">…</svg></button>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "Search button in the nav icon cluster. Its glyph is `.search-icon`.",
    },
    ComponentEntry {
        class: "search-icon",
        kind: "instance",
        parent: "nav-search-btn",
        data_attrs: &[],
        example_html: r#"<svg class="search-icon" aria-hidden="true" width="1em" height="1em">…</svg>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "The magnifier glyph. Sized in `em` and stroked with `currentColor`, so it follows the button's font-size and color rather than needing its own rule.",
    },
    ComponentEntry {
        class: "nav-theme-btn",
        kind: "instance",
        parent: "nav-icons",
        data_attrs: &[],
        example_html: r#"<button class="nav-theme-btn" type="button" aria-label="…"><svg class="theme-toggle-icon">…</svg></button>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "Light/dark toggle in the nav icon cluster. Its glyph is `.theme-toggle-icon`.",
    },
    ComponentEntry {
        class: "theme-toggle-icon",
        kind: "instance",
        parent: "nav-theme-btn",
        data_attrs: &[],
        example_html: r#"<svg class="theme-toggle-icon" aria-hidden="true" width="1em" height="1em">…</svg>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "The sun/moon glyph. One SVG whose clip path animates between states — restyle it, but do not expect two separate icons to swap.",
    },
    ComponentEntry {
        class: "nav-lang-toggle",
        kind: "chrome",
        parent: "nav-icons",
        data_attrs: &[],
        example_html: r#"<div class="nav-lang-toggle" aria-label="…"><span class="nav-lang-current">繁</span><a href="/en/" class="nav-lang-link" hreflang="en">EN</a></div>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "The language switcher. Present only when the site has more than one edition among the three the switcher resolves (English, Simplified Chinese, Traditional Chinese) — a `ja/` or `fr/` tree publishes but adds no entry here.",
    },
    ComponentEntry {
        class: "nav-lang-current",
        kind: "instance",
        parent: "nav-lang-toggle",
        data_attrs: &[],
        example_html: r#"<span class="nav-lang-current">繁</span>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "The edition being viewed, as inert text rather than a link — style the current-language affordance here.",
    },
    ComponentEntry {
        class: "nav-lang-link",
        kind: "instance",
        parent: "nav-lang-toggle",
        data_attrs: &[],
        example_html: r#"<a href="/en/" class="nav-lang-link" hreflang="en">EN</a>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "A link to another edition of the same page. Carries `hreflang`, so `[hreflang=\"en\"]` is a stable hook for per-language styling.",
    },
    // The floating nav island (ADR-049) — the small bar that appears when the
    // reader scrolls back up past the masthead on a long page. A SECOND object,
    // not the masthead re-pinned, which is why it has its own `moss-`-prefixed
    // vocabulary. Its trail is the one exception: it deliberately reuses
    // `.site-name` / `.breadcrumb-segment` / `.breadcrumb-label` /
    // `.breadcrumb-separator` from the masthead above, so a site that restyles
    // its breadcrumb restyles both at once.
    ComponentEntry {
        class: "moss-nav-island",
        kind: "chrome",
        parent: "",
        data_attrs: &[DataAttr {
            name: "data-shown",
            values: &["false", "true"],
            default: "false",
            description: "Whether the island is currently revealed. Written by the site runtime; ABSENT in the emitted HTML, which is what keeps the island invisible with JavaScript off.",
        }],
        example_html: r#"<div class="moss-nav-island" data-shown="true"><div class="moss-nav-island-bar">…</div></div>"#,
        example_markdown: "",
        status: Status::Emerging,
        since: "0",
        description: "Floating navigation island: a one-line bar, aligned to the text column, revealed on scroll-up once the masthead has left the screen. Emitted on any page with a breadcrumb trail, but it only ever shows where it can take the reader somewhere — a trail of three or more crumbs (down the tree) or a page with headings (the sections panel). On a top-level page with neither, the markup stays dormant (ADR-049 §10). Turn it off site-wide with `[site].floating_nav = false` or `--moss-nav-island-display: none`.",
    },
    ComponentEntry {
        class: "moss-nav-island-bar",
        kind: "instance",
        parent: "moss-nav-island",
        data_attrs: &[],
        example_html: r#"<div class="moss-nav-island-bar">…trail, actions, progress…</div>"#,
        example_markdown: "",
        status: Status::Emerging,
        since: "0",
        description: "The visible rounded bar. Its width follows `--moss-nav-width`/`--moss-content-width`, so it lines up with the article text rather than with the window.",
    },
    ComponentEntry {
        class: "moss-nav-island-trail",
        kind: "instance",
        parent: "moss-nav-island-bar",
        data_attrs: &[],
        example_html: r#"<nav class="moss-nav-island-trail" aria-label="Breadcrumb">…</nav>"#,
        example_markdown: "",
        status: Status::Emerging,
        since: "0",
        description: "The breadcrumb inside the island. Same segment classes as the masthead's, plus the current page as a final crumb. It never wraps: ancestors fold into `.moss-nav-island-more` until the row fits.",
    },
    ComponentEntry {
        class: "moss-nav-island-current",
        kind: "instance",
        parent: "moss-nav-island-trail",
        data_attrs: &[],
        example_html: r#"<span class="breadcrumb-segment moss-nav-island-current" aria-current="page">末代女礦工</span>"#,
        example_markdown: "",
        status: Status::Emerging,
        since: "0",
        description: "The page you are on, as the trail's last crumb. The only crumb permitted to truncate — an ancestor either fits whole or folds away.",
    },
    ComponentEntry {
        class: "moss-nav-island-more",
        kind: "instance",
        parent: "moss-nav-island-trail",
        data_attrs: &[],
        example_html: r#"<button class="moss-nav-island-more" aria-expanded="false">…</button>"#,
        example_markdown: "",
        status: Status::Emerging,
        since: "0",
        description: "Stands in for the ancestor levels the trail had to drop. Opens the levels menu on click; names them on hover via `data-tooltip`. Never opens on hover — a touch device has none, and that is the width where folding happens.",
    },
    ComponentEntry {
        class: "moss-nav-island-actions",
        kind: "instance",
        parent: "moss-nav-island-bar",
        data_attrs: &[],
        example_html: r#"<span class="moss-nav-island-actions">…</span>"#,
        example_markdown: "",
        status: Status::Emerging,
        since: "0",
        description: "Button cluster at the island's end edge. Holds the sections button only — theme, language and search stay in the masthead.",
    },
    ComponentEntry {
        class: "moss-nav-island-sections",
        kind: "instance",
        parent: "moss-nav-island-actions",
        data_attrs: &[],
        example_html: r#"<button class="moss-nav-island-sections" aria-expanded="false"><svg>…</svg></button>"#,
        example_markdown: "",
        status: Status::Emerging,
        since: "0",
        description: "Opens this page's section list. Ships `hidden` and is unhidden only once headings have been found, so a page with no headings shows no dead glyph.",
    },
    ComponentEntry {
        class: "moss-nav-island-menu",
        kind: "instance",
        parent: "moss-nav-island",
        data_attrs: &[DataAttr {
            name: "data-island-menu",
            values: &["levels", "sections"],
            default: "levels",
            description: "Which of the two menus this is: the folded ancestor levels, or the page's sections.",
        }],
        example_html: r#"<div class="moss-nav-island-menu" data-island-menu="sections">…</div>"#,
        example_markdown: "",
        status: Status::Emerging,
        since: "0",
        description: "Popover opened by `.moss-nav-island-more` or `.moss-nav-island-sections`. Every row reserves a leading gutter for the current-row rule, so the labels line up in one column whether or not a row is marked.",
    },
    ComponentEntry {
        class: "moss-breadcrumb-more",
        kind: "instance",
        parent: "",
        data_attrs: &[],
        example_html: r#"<button class="moss-breadcrumb-more" aria-expanded="false">…</button>"#,
        example_markdown: "",
        status: Status::Emerging,
        since: "0",
        description: "The masthead trail's counterpart to `.moss-nav-island-more`: stands in for the ancestor levels the trail folded, opens the levels menu on click, names them on hover via `data-tooltip`. Emitted (hidden) only when the trail has a middle to fold — three or more crumbs.",
    },
    ComponentEntry {
        class: "moss-breadcrumb-menu",
        kind: "instance",
        parent: "",
        data_attrs: &[],
        example_html: r#"<div class="moss-breadcrumb-menu" hidden>…</div>"#,
        example_markdown: "",
        status: Status::Emerging,
        since: "0",
        description: "Popover listing the masthead trail's folded ancestor levels, opened by `.moss-breadcrumb-more`. A sibling of `.nav-left` (which clips its own overflow), positioned against `.nav-content`. Same shape as `.moss-nav-island-menu`.",
    },
    ComponentEntry {
        class: "moss-nav-island-progress",
        kind: "instance",
        parent: "moss-nav-island-bar",
        data_attrs: &[],
        example_html: r#"<span class="moss-nav-island-progress"><span class="moss-nav-island-progress-fill"></span></span>"#,
        example_markdown: "",
        status: Status::Emerging,
        since: "0",
        description: "Reading-progress track along the island's own bottom edge — not a separate bar across the window. Currently measures document scroll.",
    },
    ComponentEntry {
        class: "moss-nav-island-progress-fill",
        kind: "instance",
        parent: "moss-nav-island-progress",
        data_attrs: &[],
        example_html: r#"<span class="moss-nav-island-progress-fill" style="width: 42%"></span>"#,
        example_markdown: "",
        status: Status::Emerging,
        since: "0",
        description: "The filled portion of the progress track. Its `width` is written inline by the site runtime; with JavaScript off it stays at 0 and the track reads as empty.",
    },
    ComponentEntry {
        class: "footer-default",
        kind: "chrome",
        parent: "",
        data_attrs: &[],
        example_html: r#"<p class="footer-default"><a href="/rss.xml" class="footer-link" data-external>RSS</a>…</p>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "The generated footer link row, emitted only when the site has no authored `footer.md`. Authoring a footer replaces it, so a rule targeting this stops applying the moment the site gains one.",
    },
    ComponentEntry {
        class: "footer-link",
        kind: "instance",
        parent: "footer-default",
        data_attrs: &[],
        example_html: r#"<a href="/rss.xml" class="footer-link" data-external>RSS</a>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "One link in the generated footer row (RSS and similar). Off-site ones also carry `data-external`.",
    },
    ComponentEntry {
        class: "moss-child-section-divider",
        kind: "instance",
        parent: "",
        data_attrs: &[],
        example_html: r#"<hr class="moss-child-section-divider" />"#,
        example_markdown: "",
        status: Status::Emerging,
        since: "0",
        description: "Divider rule between auto-generated child sections.",
    },
    ComponentEntry {
        // Source of truth: `crates/moss-core/src/ast/shortcode_extract.rs`
        // (the unknown-name branch around line 1282). components_sync_test
        // only greps emitter source for `class="moss-..."` literals — this
        // class is assembled via `render_div_open`, so a regression here
        // will NOT be caught by that test; keep this entry in sync by hand.
        class: "moss-unknown-shortcode",
        kind: "standalone",
        parent: "",
        data_attrs: &[DataAttr {
            name: "data-name",
            values: &[],
            default: "",
            description: "The unrecognised shortcode name, as written by the author.",
        }],
        example_html: r#"<div class="moss-unknown-shortcode" data-name="foo">

<p>body parsed as markdown</p>

</div>"#,
        example_markdown: ":::foo\nbody parsed as markdown\n:::",
        status: Status::Confirmed,
        since: "0",
        description: "Fallback wrapper emitted for any `:::name` fence whose name is not a registered shortcode. The body is still parsed as markdown and a build warning names the shortcode, so a misspelling degrades to a styled region rather than losing content.",
    },
    // -------------------------------------------------------------------
    // Syntax highlight tokens (emitted by syntect inside <code>).
    // -------------------------------------------------------------------
    ComponentEntry {
        class: "moss-hl-keyword",
        kind: "instance",
        parent: "",
        data_attrs: &[],
        example_html: r#"<span class="moss-hl-keyword">if</span>"#,
        example_markdown: "",
        status: Status::Emerging,
        since: "0",
        description: "Syntax-highlight token: keyword.",
    },
    ComponentEntry {
        class: "moss-hl-string",
        kind: "instance",
        parent: "",
        data_attrs: &[],
        example_html: r#"<span class="moss-hl-string">"hi"</span>"#,
        example_markdown: "",
        status: Status::Emerging,
        since: "0",
        description: "Syntax-highlight token: string literal.",
    },
    ComponentEntry {
        class: "moss-hl-comment",
        kind: "instance",
        parent: "",
        data_attrs: &[],
        example_html: r#"<span class="moss-hl-comment">// note</span>"#,
        example_markdown: "",
        status: Status::Emerging,
        since: "0",
        description: "Syntax-highlight token: comment.",
    },
    ComponentEntry {
        class: "moss-hl-function",
        kind: "instance",
        parent: "",
        data_attrs: &[],
        example_html: r#"<span class="moss-hl-function">render</span>"#,
        example_markdown: "",
        status: Status::Emerging,
        since: "0",
        description: "Syntax-highlight token: function name.",
    },
    ComponentEntry {
        class: "moss-hl-type",
        kind: "instance",
        parent: "",
        data_attrs: &[],
        example_html: r#"<span class="moss-hl-type">String</span>"#,
        example_markdown: "",
        status: Status::Emerging,
        since: "0",
        description: "Syntax-highlight token: type name.",
    },
    ComponentEntry {
        class: "moss-hl-number",
        kind: "instance",
        parent: "",
        data_attrs: &[],
        example_html: r#"<span class="moss-hl-number">42</span>"#,
        example_markdown: "",
        status: Status::Emerging,
        since: "0",
        description: "Syntax-highlight token: numeric literal.",
    },
    ComponentEntry {
        class: "moss-hl-operator",
        kind: "instance",
        parent: "",
        data_attrs: &[],
        example_html: r#"<span class="moss-hl-operator">+</span>"#,
        example_markdown: "",
        status: Status::Emerging,
        since: "0",
        description: "Syntax-highlight token: operator.",
    },
    ComponentEntry {
        class: "moss-hl-builtin",
        kind: "instance",
        parent: "",
        data_attrs: &[],
        example_html: r#"<span class="moss-hl-builtin">print</span>"#,
        example_markdown: "",
        status: Status::Emerging,
        since: "0",
        description: "Syntax-highlight token: builtin identifier.",
    },
    ComponentEntry {
        class: "moss-hl-tag",
        kind: "instance",
        parent: "",
        data_attrs: &[],
        example_html: r#"<span class="moss-hl-tag">div</span>"#,
        example_markdown: "",
        status: Status::Emerging,
        since: "0",
        description: "Syntax-highlight token: markup tag name.",
    },
    ComponentEntry {
        class: "moss-hl-attr",
        kind: "instance",
        parent: "",
        data_attrs: &[],
        example_html: r#"<span class="moss-hl-attr">class</span>"#,
        example_markdown: "",
        status: Status::Emerging,
        since: "0",
        description: "Syntax-highlight token: attribute name.",
    },
    ComponentEntry {
        class: "moss-hl-meta",
        kind: "instance",
        parent: "",
        data_attrs: &[],
        example_html: r#"<span class="moss-hl-meta">@derive</span>"#,
        example_markdown: "",
        status: Status::Emerging,
        since: "0",
        description: "Syntax-highlight token: meta/annotation.",
    },
    ComponentEntry {
        class: "moss-hl-addition-bg",
        kind: "instance",
        parent: "",
        data_attrs: &[],
        example_html: r#"<span class="moss-hl-addition-bg">+ added line</span>"#,
        example_markdown: "",
        status: Status::Emerging,
        since: "0",
        description: "Syntax-highlight diff token: added-line background.",
    },
    ComponentEntry {
        class: "moss-hl-deletion",
        kind: "instance",
        parent: "",
        data_attrs: &[],
        example_html: r#"<span class="moss-hl-deletion">- removed line</span>"#,
        example_markdown: "",
        status: Status::Emerging,
        since: "0",
        description: "Syntax-highlight diff token: removed-line text.",
    },
    ComponentEntry {
        class: "moss-hl-deletion-bg",
        kind: "instance",
        parent: "",
        data_attrs: &[],
        example_html: r#"<span class="moss-hl-deletion-bg">- removed line</span>"#,
        example_markdown: "",
        status: Status::Emerging,
        since: "0",
        description: "Syntax-highlight diff token: removed-line background.",
    },
    ComponentEntry {
        class: "moss-recent",
        kind: "container",
        parent: "",
        data_attrs: &[],
        example_html: r#"<ul class="moss-recent">
  <li><a href="/posts/spring-notes/">Spring notes</a><div class="moss-recent__date">2026-04-12</div><div class="moss-recent__desc">A walk through the garden.</div></li>
</ul>"#,
        example_markdown: ":::recent {count=5 since=\"2026-01-01\"}\n:::\n",
        status: Status::Emerging,
        since: "0",
        description: "Auto-generated list of recent posts. Sorted newest-first; date and description slots are filled per child. No default CSS in the bundled theme — theme authors style it freely. IMPORTANT: emitted by the EMAIL/newsletter path only. On a web page, `:::recent` renders its fallback body as ordinary markdown and emits no list, because the per-page processor has no access to the build's aggregate document slice; a `:::recent` block with an empty body therefore produces nothing at all on a web page. To list posts on a page today, rely on the automatic child listing a folder home emits (`moss-cards`), and give any `:::recent` block a fallback body.",
    },
    ComponentEntry {
        class: "moss-recent__date",
        kind: "instance",
        parent: "moss-recent",
        data_attrs: &[],
        example_html: r#"<div class="moss-recent__date">2026-04-12</div>"#,
        example_markdown: "",
        status: Status::Emerging,
        since: "0",
        description: "Per-entry date slot inside `.moss-recent` (BEM child). Format is `YYYY-MM-DD`, derived from frontmatter `date`. Empty string when the post lacks a parseable date.",
    },
    ComponentEntry {
        class: "moss-recent__desc",
        kind: "instance",
        parent: "moss-recent",
        data_attrs: &[],
        example_html: r#"<div class="moss-recent__desc">A walk through the garden.</div>"#,
        example_markdown: "",
        status: Status::Emerging,
        since: "0",
        description: "Per-entry description slot inside `.moss-recent` (BEM child). Sourced from frontmatter `description`; empty when unset.",
    },
    // -------------------------------------------------------------------
    // Ambient loop video — JS-injected wrapper + toggle (§3.5).
    // The <video data-loop> synthesizer emits `data-loop` on the <video>;
    // ambient-video.ts wraps it at init time.
    // -------------------------------------------------------------------
    ComponentEntry {
        class: "moss-ambient-video",
        kind: "standalone",
        parent: "",
        data_attrs: &[
            DataAttr {
                name: "data-paused",
                values: &[],
                default: "",
                description: "Boolean presence flag set by ambient-video.ts when the video is paused (user-initiated or reduced-motion guard). CSS uses `[data-paused]` to keep the toggle visible.",
            },
        ],
        example_html: r#"<div class="moss-ambient-video">
  <video data-loop src="clip.mp4" autoplay muted loop playsinline preload="metadata"></video>
  <button class="moss-ambient-toggle" type="button" aria-label="Pause video">⏸</button>
</div>"#,
        example_markdown: "![[clip.mp4|loop]]",
        status: Status::Emerging,
        since: "1",
        description: "JS-injected wrapper around a `video[data-loop]` element. Provides the positioning context for `.moss-ambient-toggle` and the `[data-paused]` state hook. Not emitted by the Rust synthesizer — ambient-video.ts creates it at init.",
    },
    ComponentEntry {
        class: "moss-ambient-toggle",
        kind: "instance",
        parent: "moss-ambient-video",
        data_attrs: &[],
        example_html: r#"<button class="moss-ambient-toggle" type="button" aria-label="Pause video">⏸</button>"#,
        example_markdown: "",
        status: Status::Emerging,
        since: "1",
        description: "Chrome-free pause/play toggle button for ambient loop videos. Injected by ambient-video.ts. Keyboard-focusable; `aria-label` toggles between \"Pause video\" and \"Play video\". Visible on hover/focus of `.moss-ambient-video` and always visible when `[data-paused]`. Satisfies WCAG 2.2.2 Level A (Pause, Stop, Hide).",
    },
    // -------------------------------------------------------------------
    // LaTeX math (ADR-030). P1 emits the escaped source in a marked
    // `<code>`; P2 replaces the element's *contents* with a typeset
    // `<svg>` while keeping the class and `data-moss-math` stable, so a
    // theme selector written against P1 keeps working across the upgrade.
    // -------------------------------------------------------------------
    ComponentEntry {
        class: "moss-math",
        kind: "standalone",
        parent: "",
        data_attrs: &[
            DataAttr {
                name: "data-moss-math",
                values: &["inline", "display"],
                default: "inline",
                description: "Which delimiter produced the equation: `inline` for `$…$`, `display` for `$$…$$`. Carries the distinction to CSS and to the typesetter so neither has to re-derive it from context — a theme can select on it today to centre display math; moss ships no math stylesheet of its own yet, so both variants currently inherit plain `<code>` styling.",
            },
        ],
        example_html: r#"<code class="moss-math" data-moss-math="inline">$E = mc^2$</code>"#,
        example_markdown: "Energy $E = mc^2$.",
        status: Status::Emerging,
        since: "1",
        description: "A LaTeX equation. In P1 the element holds the author's own markdown source — `$` / `$$` delimiters included — HTML-escaped: an honest fallback that never shows a blank where an equation was written, and never deletes the delimiters of prose that merely looked like math. Requires `[site].math` (default on).",
    },
    ComponentEntry {
        class: "moss-math-scroll",
        kind: "container",
        parent: "",
        data_attrs: &[],
        example_html: r#"<div class="moss-math-scroll"><svg class="moss-math" data-moss-math="display">…</svg></div>"#,
        example_markdown: "$$E = mc^2$$",
        status: Status::Emerging,
        since: "1",
        description: "Horizontal-scroll container the build path wraps around typeset display math (`svg.moss-math[data-moss-math=\"display\"]`). On a narrow viewport a wide equation scrolls inside this box at its natural size rather than shrinking to unreadability or pushing the page into horizontal overflow. Emitted only by P2's typeset path; the P1 `<code>` fallback is never wrapped. A display SVG left unwrapped still cannot overflow the page — it falls back to scaling down via `max-width: 100%`.",
    },
    ComponentEntry {
        class: "moss-table-scroll",
        kind: "container",
        parent: "",
        data_attrs: &[],
        example_html: r#"<div class="moss-table-scroll" tabindex="0">
  <table>…</table>
</div>"#,
        example_markdown: "| Name | Subs |\n| --- | --- |\n| a | 1,200 |",
        status: Status::Emerging,
        since: "1",
        description: "Horizontal-scroll wrapper the renderer emits around every Markdown table and every CSV/TSV embed (`.moss-embed[data-type=\"table\"]`). Keeps the `<table>` semantically intact (unlike a `display:block` table, which breaks column layout and assistive-tech table semantics) while letting a wide table scroll inside its own box instead of pushing the page into horizontal overflow. `tabindex=\"0\"` makes an overflowing table keyboard-scrollable.",
    },
    ComponentEntry {
        class: "moss-col-right",
        kind: "instance",
        parent: "moss-table-scroll",
        data_attrs: &[],
        example_html: r#"<th class="moss-col-right">订阅数</th>
<td class="moss-col-right">1,457,776</td>"#,
        example_markdown: "| Subs |\n| --: |\n| 1,457,776 |",
        status: Status::Emerging,
        since: "1",
        description: "Right-aligned table cell (`<th>`/`<td>`). Applied to a whole column when the author right-aligned it in GFM (`|--:|`) or when the column auto-detects as numeric, so figures register on their trailing digits. Pairs with the table's `font-variant-numeric: tabular-nums`.",
    },
    ComponentEntry {
        class: "moss-col-center",
        kind: "instance",
        parent: "moss-table-scroll",
        data_attrs: &[],
        example_html: r#"<th class="moss-col-center">Status</th>
<td class="moss-col-center">✓</td>"#,
        example_markdown: "| Status |\n| :-: |\n| ✓ |",
        status: Status::Emerging,
        since: "1",
        description: "Center-aligned table cell (`<th>`/`<td>`). Applied to a whole column the author center-aligned in GFM (`|:-:|`).",
    },
    ComponentEntry {
        class: "moss-search",
        kind: "chrome",
        parent: "",
        data_attrs: &[],
        example_html: r#"<div class="moss-search" id="moss-search" hidden>
  <div class="moss-search__backdrop"></div>
  <div class="moss-search__panel" role="dialog" aria-modal="true" aria-label="Search">
    <div class="moss-search__field"><input class="moss-search__input" role="combobox"></div>
    <div class="moss-search__progress" hidden></div>
    <div class="moss-search__seam"></div>
    <div class="moss-search__body">
      <p class="moss-search__status" role="status" hidden></p>
      <ul class="moss-search__results" role="listbox">
        <li class="moss-search__row">
          <a class="moss-search__link" role="option" href="/posts/foo/">
            <span class="moss-search__title">Title</span>
            <span class="moss-search__excerpt">…a <mark>match</mark>…</span>
          </a>
        </li>
      </ul>
    </div>
  </div>
</div>"#,
        example_markdown: "",
        status: Status::Emerging,
        since: "1",
        description: "Site-search overlay. Not emitted by the build — the client runtime (`_moss/js/search.<hash>.js`, shipped only when the build wrote a Pagefind index) constructs this subtree lazily on the first open, so a reader who never searches downloads no index and materializes no DOM. Opened by the nav's `.nav-search-btn`, by `/`, or by ⌘K/Ctrl+K. BEM children carry the interior: `__backdrop` (translucent page-coloured scrim, not an opaque modal takeover), `__panel` (top-anchored at 18vh, fixed 18px radius at any height), `__field`/`__input`, `__progress` (1px accent hairline, delayed 200ms so fast queries never flash it), `__seam` (hairline inset by the corner radius), `__status` (idle / no-matches line, sharing one vertical slot with the results so the panel never jumps), `__results`/`__row`/`__link`/`__title`/`__excerpt`. Selection is a 2px `--moss-color-ui-accent` left border plus a ~4% accent tint — never a solid fill block. `<mark>` inside `__excerpt` is Pagefind's own term highlighting, restyled to colour emphasis rather than a highlighter box.",
    },
    ComponentEntry {
        class: "moss-footnotes",
        kind: "container",
        parent: "",
        data_attrs: &[],
        example_html: r##"<section class="moss-footnotes" role="doc-endnotes">
<ol>
<li id="fn-1"><p>The note. <a class="moss-footnote-backref" href="#fnref-1" role="doc-backlink" aria-label="Back to reference 1">&#8617;&#xFE0E;</a></p>
</li>
</ol>
</section>"##,
        example_markdown: "Text[^1].\n\n[^1]: The note.",
        status: Status::Emerging,
        since: "1",
        description: "The document's endnote section, appended after the body by the renderer. Holds one `<li id=\"fn-N\">` per footnote in first-reference order, whatever depth the author wrote the definition at — a definition inside a blockquote or a list item is hoisted here too. Present only on pages that define at least one footnote. `role=\"doc-endnotes\"` (DPUB-ARIA) names the region for assistive tech.",
    },
    ComponentEntry {
        class: "moss-footnote-ref",
        kind: "instance",
        parent: "moss-footnotes",
        data_attrs: &[],
        example_html: r##"<sup class="moss-footnote-ref" id="fnref-1"><a href="#fn-1" role="doc-noteref">1</a></sup>"##,
        example_markdown: "Text[^1].\n\n[^1]: The note.",
        status: Status::Emerging,
        since: "1",
        description: "The in-body footnote marker: a superscript number linking down to its note. The number is first-reference order, not the author's label, so `[^method]` and `[^1]` both print as ordinals. A second marker for the same note takes id `fnref-N-2`, `fnref-N-3`, … so each has its own back-link.",
    },
    ComponentEntry {
        class: "moss-footnote-backref",
        kind: "instance",
        parent: "moss-footnotes",
        data_attrs: &[],
        example_html: r##"<a class="moss-footnote-backref" href="#fnref-1" role="doc-backlink" aria-label="Back to reference 1">&#8617;&#xFE0E;</a>"##,
        example_markdown: "Text[^1].\n\n[^1]: The note.",
        status: Status::Emerging,
        since: "1",
        description: "The return arrow at the end of a note, linking back to the marker that sent the reader there. One per marker, so a note referenced twice ends with two arrows. A note nobody referenced has none. The arrow carries VARIATION SELECTOR-15 (`&#xFE0E;`) so mobile Chrome renders it as plain text rather than a coloured emoji.",
    },
    // Classes the site JavaScript reads, declared 2026-08-09.
    //
    // moss ships JS into every built site, and that JS finds what it acts on by
    // class name. So a class the script queries is as much a published name as
    // one a stylesheet targets — rename it and the feature dies silently, since
    // a selector that matches nothing does not throw. `site_js_selectors_match_
    // components_table` (src-tauri/tests/components_sync_test.rs) now checks
    // that direction; these are the twenty classes it found undeclared. All of
    // them predate the `moss-` convention, hence the block below in
    // `UNPREFIXED_LEGACY_CLASSES`.
    ComponentEntry {
        class: "container",
        kind: "chrome",
        parent: "",
        data_attrs: &[
            DataAttr {
                name: "data-share-cover",
                values: &[],
                default: "",
                description: "The page's own cover image, as a same-origin URL: its `:::hero` image, else its `cover:` frontmatter. Emitted on the `<article>` only, and only when the page has one of those — absent means the page genuinely has no cover, and never the auto-generated og card. The share-card runtime reads it instead of hunting for the cover in the markup; a theme can use `article.container[data-share-cover]` to tell a page that has a cover picture from one that does not.",
            },
        ],
        example_html: r#"<article class="container" data-share-cover="/img/cover.webp">…</article>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "The reading-width wrapper. It is the `<article>` on a page or post, and also the `<nav class=\"main-nav container\">` — one class, one measure, so the masthead lines up with the text under it. Site JS treats `article.container` as \"the current document\": immersive mode promotes its direct-child iframes, and the share card reads its `data-share-cover`.",
    },
    ComponentEntry {
        class: "nav-content",
        kind: "chrome",
        parent: "main-nav",
        data_attrs: &[],
        example_html: r#"<nav class="main-nav container"><div class="nav-content">…</div></nav>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "The row inside the nav bar that holds `.nav-left` and `.nav-right`. It is the box the responsive nav measures itself against: when the two groups no longer fit on one line, `nav-split.ts` sets `data-nav-split` on this element and the links move to a second row.",
    },
    ComponentEntry {
        class: "font-anchor",
        kind: "chrome",
        parent: "date-line",
        data_attrs: &[],
        example_html: r#"<div class="font-anchor"><button class="font-trigger size-std" aria-expanded="false"></button><div class="font-pill" id="fontPill">…</div></div>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "Positioning box for the reading-preferences control that sits at the end of an article's date line. Holds the trigger and the size pills; exists so the pills can be positioned against the trigger rather than the page.",
    },
    ComponentEntry {
        class: "font-trigger",
        kind: "instance",
        parent: "font-anchor",
        data_attrs: &[],
        example_html: r#"<button class="font-trigger size-std" aria-label="Reading preferences" aria-expanded="false" type="button"></button>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "The button that opens the reading-size pills. Its second class tracks the chosen size (`size-std` by default), so a theme can restyle the trigger per size without reading state from JS.",
    },
    ComponentEntry {
        class: "cover-thumb",
        kind: "instance",
        parent: "moss-card-cover",
        data_attrs: &[],
        example_html: r#"<div class="moss-card-cover"><video src="clip.mp4" muted loop playsinline preload="metadata"></video><img src="clip.thumb.jpg" alt="A clip" class="cover-thumb" /></div>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "The still frame stacked over a video cover. It is what the reader sees until they hover: `card-video.ts` fades this image out and starts the `<video>` underneath, and fades it back in on leave. Emitted only for video covers, inside `.moss-card-cover` or `.moss-collection-cover`.",
    },
    ComponentEntry {
        class: "media-item",
        kind: "instance",
        parent: "",
        data_attrs: &[
            DataAttr { name: "data-type", values: &["image", "video", "iframe"], default: "image", description: "Which lightbox surface opens for this item." },
            DataAttr { name: "data-src", values: &[], default: "", description: "Full-size source the lightbox loads." },
            DataAttr { name: "data-title", values: &[], default: "", description: "Caption shown under the lightbox." },
            DataAttr { name: "data-article", values: &[], default: "", description: "URL of the article the item came from, linked from the caption." },
        ],
        example_html: r#"<figure class="media-item" tabindex="0" data-type="image" data-src="/img/full.webp" data-title="Kyiv" data-article="/posts/kyiv/">…</figure>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "One tile on the media-collection page. `fullscreen.ts` collects these in document order to build the lightbox playlist, so their order on the page is the order the arrows step through.",
    },
    ComponentEntry {
        class: "lightbox-content",
        kind: "chrome",
        parent: "",
        data_attrs: &[],
        example_html: r#"<div class="lightbox-content"><img class="lightbox-image" hidden /><video class="lightbox-video" controls hidden></video><iframe class="lightbox-iframe" hidden></iframe></div>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "The stage of the media-collection lightbox. Holds all three players at once; `fullscreen.ts` unhides whichever one matches the opened item's `data-type` and leaves the others hidden.",
    },
    ComponentEntry {
        class: "lightbox-image",
        kind: "instance",
        parent: "lightbox-content",
        data_attrs: &[],
        example_html: r#"<img class="lightbox-image" src="" alt="" hidden />"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "The lightbox's image player. Emitted empty and hidden; its `src` is filled in when an image item opens.",
    },
    ComponentEntry {
        class: "lightbox-video",
        kind: "instance",
        parent: "lightbox-content",
        data_attrs: &[],
        example_html: r#"<video class="lightbox-video" controls hidden></video>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "The lightbox's video player. Emitted empty and hidden; paused and cleared when the lightbox closes so audio never outlives the overlay.",
    },
    ComponentEntry {
        class: "lightbox-iframe",
        kind: "instance",
        parent: "lightbox-content",
        data_attrs: &[],
        example_html: r#"<iframe class="lightbox-iframe" hidden></iframe>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "The lightbox's embed surface, for media items that are an external player rather than a file.",
    },
    ComponentEntry {
        class: "lightbox-title",
        kind: "instance",
        parent: "",
        data_attrs: &[],
        example_html: r#"<p class="lightbox-title"></p>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "Caption line under the lightbox stage. Filled from the open item's `data-title`.",
    },
    ComponentEntry {
        class: "lightbox-article-link",
        kind: "instance",
        parent: "",
        data_attrs: &[],
        example_html: r#"<a class="lightbox-article-link" href="">View in article →</a>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "The way back from a media tile to the article it appeared in. Its `href` is filled from the open item's `data-article`, and it is hidden when the item has none.",
    },
    ComponentEntry {
        class: "lightbox-close",
        kind: "instance",
        parent: "",
        data_attrs: &[],
        example_html: r#"<button class="lightbox-close" aria-label="Close">&times;</button>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "Dismisses the media-collection lightbox. Escape does the same thing.",
    },
    ComponentEntry {
        class: "lightbox-next",
        kind: "instance",
        parent: "",
        data_attrs: &[],
        example_html: r#"<button class="lightbox-nav lightbox-next" aria-label="Next">&rsaquo;</button>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "Steps forward through the `.media-item` playlist, wrapping at the end. Carries `lightbox-nav` as well, which styles both arrows together.",
    },
    ComponentEntry {
        class: "lightbox-prev",
        kind: "instance",
        parent: "",
        data_attrs: &[],
        example_html: r#"<button class="lightbox-nav lightbox-prev" aria-label="Previous">&lsaquo;</button>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "Steps backward through the `.media-item` playlist, wrapping at the start.",
    },
    ComponentEntry {
        class: "comments-toggle",
        kind: "instance",
        parent: "moss-comments",
        data_attrs: &[],
        example_html: r#"<summary class="comments-toggle"><svg class="comments-icon">…</svg><span>3 comments</span><svg class="comments-chevron">…</svg></summary>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "The `<summary>` that opens and closes the comment thread. Its `<span>` holds the count, which the client rewrites as comments arrive — so the span is a contract of its own, not decoration.",
    },
    ComponentEntry {
        class: "comment-list",
        kind: "container",
        parent: "moss-comments",
        data_attrs: &[],
        example_html: r#"<ol class="comment-list"><li class="comment-item" …>…</li></ol>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "The top-level comment thread, rendered server-side at build time and then hydrated in place (ADR-025). New comments are appended here by the client rather than replacing the list, so server-rendered and live comments share one shape.",
    },
    ComponentEntry {
        class: "comment-item",
        kind: "instance",
        parent: "comment-list",
        data_attrs: &[
            DataAttr { name: "data-comment-source", values: &["artalk"], default: "artalk", description: "Where the comment came from — moss's own server, or a syndicated platform." },
            DataAttr { name: "data-comment-id", values: &[], default: "", description: "Identifier within that source. Unique only per source, which is why nesting keys on the pair." },
        ],
        example_html: r#"<li class="comment-item" id="comment-artalk-12" data-comment-source="artalk" data-comment-id="12">…</li>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "One comment. Holds a `.comment-header`, a `.comment-body`, and — if it has replies — a nested `.comment-replies`. The `data-comment-*` pair is how the client matches a live comment to the one already on the page instead of rendering it twice.",
    },
    ComponentEntry {
        class: "comment-replies",
        kind: "container",
        parent: "comment-item",
        data_attrs: &[],
        example_html: r#"<ol class="comment-replies"><li class="comment-item" …>…</li></ol>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "Nested replies under a comment, same shape as `.comment-list`. Emitted only when a comment has replies; the client creates one on demand when the first reply arrives.",
    },
    ComponentEntry {
        class: "comment-reply-btn",
        kind: "instance",
        parent: "comment-item",
        data_attrs: &[
            DataAttr { name: "data-reply-id", values: &[], default: "", description: "The comment being replied to." },
            DataAttr { name: "data-reply-name", values: &[], default: "", description: "Display name of its author, used to prefill the form." },
        ],
        example_html: r#"<button type="button" class="comment-reply-btn" data-reply-id="12" data-reply-name="Yi">↩︎ Reply</button>"#,
        example_markdown: "",
        status: Status::Confirmed,
        since: "0",
        description: "Moves the comment form under this comment so the reply is written where it will appear. Emitted only for comments moss can reply to; a syndicated comment gets a link out to its own platform instead.",
    },
];

/// Implementation classes that are emitted by moss for internal functionality
/// but must not appear in the public theme-facing contract (`moss describe` /
/// `docs/reference/contract.md`). These classes ARE present in `COMPONENTS` for
/// the sync-test to validate their HTML class literals, but `is_public()` hides
/// them from agents, themes, and `reference.md` generation.
const INTERNAL_CLASSES: &[&str] = &[
    "moss-apply",
    "moss-apply-form",
    "moss-apply-matters",
    "moss-apply-hp",
    "moss-apply-status",
    "moss-apply-helper",
];

impl ComponentEntry {
    /// True for entries that belong in the public, agent/theme-facing surface.
    /// v1 rule: not retired AND not an internal implementation class.
    ///
    /// Internal classes (e.g. all `moss-apply*`) stay in COMPONENTS so the
    /// sync-test can validate them, but they must not surface in `moss describe`
    /// or `docs/reference/contract.md` — they are subject to change at any time.
    pub fn is_public(&self) -> bool {
        self.status != Status::Retired && !INTERNAL_CLASSES.contains(&self.class)
    }
}

/// Iterator over class names with `Status::Retired`. Used by the build
/// pipeline's theme lint to warn users about pre-v1 vocabulary.
///
/// Exposed as an iterator over `&'static str` so callers don't need to
/// import the `Status` enum (keeps moss-core's surface narrow).
pub fn retired_class_names() -> impl Iterator<Item = &'static str> {
    COMPONENTS.iter()
        .filter(|e| e.status == Status::Retired)
        .map(|e| e.class)
}

#[cfg(test)]
mod tests {
    use super::*;

    /// Orphan-gate: every class in `INTERNAL_CLASSES` must exist as a `class`
    /// in `COMPONENTS`. If a class is renamed in the emitter *and* in
    /// `INTERNAL_CLASSES` but forgotten in `COMPONENTS`, it would silently
    /// re-enter the public contract surface (`is_public()` only hides known
    /// internals). This test prevents that gap.
    #[test]
    fn every_internal_class_has_a_components_entry() {
        let component_classes: std::collections::HashSet<&'static str> =
            COMPONENTS.iter().map(|e| e.class).collect();
        for &internal in INTERNAL_CLASSES {
            assert!(
                component_classes.contains(internal),
                "INTERNAL_CLASSES entry '{}' has no matching entry in COMPONENTS — \
                 add a ComponentEntry for it or remove it from INTERNAL_CLASSES",
                internal
            );
        }
    }
}