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",
];

/// 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>`).",
            },
        ],
        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 the default legibility scrim leaves white overlay text under 4.5:1; site.css swaps in a stronger gradient. Emitted only when the hero also carries overlay text. Absent = mid-tone or dark image, no overlay, or an unparseable colour — all keep 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"><span aria-hidden="true">#</span></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 auto-injected `moss-article-title` H1 is emitted separately and gets no anchor.",
    },
    // -------------------------------------------------------------------
    // 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.",
            },
        ],
        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.",
    },
];

/// 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
            );
        }
    }
}