# manifest

URL: /chirp-ui/api/manifest/
Section: api
Description: Agent-groundable manifest of the chirp-ui component surface.

This module publishes the component registry (``chirp_ui.components.COMPONENTS``
plus ``chirp_ui.tokens.TOKEN_CATALOG``) as a stable JSON snapshot. AI agents
and docs tooling can read the manifest to cite real classes, tokens, slots,
and templates instead of plausible-sounding ones.

Schema
------
``{"schema": "chirpui-manifest@5", "version": "<pkg>", "components": {...},
 "tokens": {...}, "theme_packs": [...], "stats": {...}}``

* ``components`` keys sorted; each entry contains ``block``, ``variants``,
  ``sizes``, ``modifiers``, ``elements``, ``slots``, ``tokens``,
  ``extra_emits``, ``trim_emits``, ``emits``, ``template``, ``category``,
  ``maturity``, ``role``, ``authoring``, ``requires``, plus the ``@2``
  additions ``macro``, ``params``, and ``lineno``, the ``@3`` composition
  additions ``composes``, ``slot_forwards``, and ``slots_yielded``, and the
  ``@4`` appearance/tone additions ``appearances`` and ``tones``.
* ``params`` is a list of ``{"name": str, "has_default": bool,
  "is_required": bool}`` derived from the template AST via
  `chirp_ui._macro_introspect`. Empty when the descriptor has no
  template, the macro cannot be resolved, or the template has no
  ``{% def %}`` matching the resolved name.
* ``macro`` is the resolved macro identifier (``descriptor.macro`` if set,
  else ``block.replace("-", "_")``). ``null`` when the descriptor has no
  template or no matching macro is found.
* ``lineno`` is the source line of the ``{% def %}`` tag (``0`` when
  unavailable).
* ``slots`` is the sorted union of ``descriptor.slots``, direct slots
  extracted from the macro body, and yielded slots accepted by composite
  wrappers. The unnamed default slot is represented as ``""``. Hand-authored
  descriptor entries can over-declare (e.g. for documentation), but the
  manifest never under-reports a real slot.
* ``slots_extracted`` is the AST-derived slot list (sorted, default = ``""``)
  exposed separately so parity tests can spot descriptor↔template drift
  without losing the merged ``slots`` contract.
* ``slots_yielded`` is the source-derived list of ``{% yield %}`` /
  ``{% yield name %}`` caller slots. Composite forwarding metadata is explicit
  in ``composes`` and ``slot_forwards``.
* ``provides`` / ``consumes`` are sorted lists of context keys (e.g.
  ``"_card_variant"``) sourced from `chirp_ui.inspect`. A key is
  attributed to the macro whose ``{% def %}`` lineno is the largest one
  preceding the ``{% provide %}`` / ``consume()`` site.
* ``description`` is the stripped text inside the leading
  ``{#- chirp-ui: ... -#}`` doc-block of the template file. One block per
  file, covering every macro; empty string when the descriptor has no
  template. New chirp-ui templates must carry a doc-block
  (``tests/test_description_coverage.py``).
* ``tokens`` keys sorted; each entry is ``{"category": …, "scope": …}``.
* ``theme_packs`` lists packaged token-only theme CSS resources in stable
  catalog order.
* ``stats`` aggregates counts, including ``components_with_params``, a
  ``registry_debt`` scorecard for descriptor/CSS reconciliation burn-down,
  and a ``manifest_quality`` scorecard for agent-facing metadata coverage.

Deterministic: two calls to `build_manifest`() yield byte-identical JSON.

CLI
---
``python -m chirp_ui.manifest --json`` writes JSON to stdout.

See ``docs/plans/done/PLAN-agent-grounding-depth.md`` and
``docs/DESIGN-manifest-signature-extraction.md``.

---

> For a complete page index, fetch /chirp-ui/llms.txt.

# manifest

Agent-groundable manifest of the chirp-ui component surface.

This module publishes the component registry (``chirp_ui.components.COMPONENTS``
plus ``chirp_ui.tokens.TOKEN_CATALOG``) as a stable JSON snapshot. AI agents
and docs tooling can read the manifest to cite real classes, tokens, slots,
and templates instead of plausible-sounding ones.

Schema
------
``{"schema": "chirpui-manifest@5", "version": "<pkg>", "components": {...},
"tokens": {...}, "theme_packs": [...], "stats": {...}}``

* ``components`` keys sorted; each entry contains ``block``, ``variants``,
``sizes``, ``modifiers``, ``elements``, ``slots``, ``tokens``,
``extra_emits``, ``trim_emits``, ``emits``, ``template``, ``category``,
``maturity``, ``role``, ``authoring``, ``requires``, plus the ``@2``
additions ``macro``, ``params``, and ``lineno``, the ``@3`` composition
additions ``composes``, ``slot_forwards``, and ``slots_yielded``, and the
``@4`` appearance/tone additions ``appearances`` and ``tones``.
* ``params`` is a list of ``{"name": str, "has_default": bool,
"is_required": bool}`` derived from the template AST via
`chirp_ui._macro_introspect`. Empty when the descriptor has no
template, the macro cannot be resolved, or the template has no
``{% def %}`` matching the resolved name.
* ``macro`` is the resolved macro identifier (``descriptor.macro`` if set,
else ``block.replace("-", "_")``). ``null`` when the descriptor has no
template or no matching macro is found.
* ``lineno`` is the source line of the ``{% def %}`` tag (``0`` when
unavailable).
* ``slots`` is the sorted union of ``descriptor.slots``, direct slots
extracted from the macro body, and yielded slots accepted by composite
wrappers. The unnamed default slot is represented as ``""``. Hand-authored
descriptor entries can over-declare (e.g. for documentation), but the
manifest never under-reports a real slot.
* ``slots_extracted`` is the AST-derived slot list (sorted, default = ``""``)
exposed separately so parity tests can spot descriptor↔template drift
without losing the merged ``slots`` contract.
* ``slots_yielded`` is the source-derived list of ``{% yield %}`` /
``{% yield name %}`` caller slots. Composite forwarding metadata is explicit
in ``composes`` and ``slot_forwards``.
* ``provides`` / ``consumes`` are sorted lists of context keys (e.g.
``"_card_variant"``) sourced from `chirp_ui.inspect`. A key is
attributed to the macro whose ``{% def %}`` lineno is the largest one
preceding the ``{% provide %}`` / ``consume()`` site.
* ``description`` is the stripped text inside the leading
``{#- chirp-ui: ... -#}`` doc-block of the template file. One block per
file, covering every macro; empty string when the descriptor has no
template. New chirp-ui templates must carry a doc-block
(``tests/test_description_coverage.py``).
* ``tokens`` keys sorted; each entry is ``{"category": …, "scope": …}``.
* ``theme_packs`` lists packaged token-only theme CSS resources in stable
catalog order.
* ``stats`` aggregates counts, including ``components_with_params``, a
``registry_debt`` scorecard for descriptor/CSS reconciliation burn-down,
and a ``manifest_quality`` scorecard for agent-facing metadata coverage.

Deterministic: two calls to `build_manifest`() yield byte-identical JSON.

CLI
---
``python -m chirp_ui.manifest --json`` writes JSON to stdout.

See ``docs/plans/done/PLAN-agent-grounding-depth.md`` and
``docs/DESIGN-manifest-signature-extraction.md``.

module

Agent-groundable manifest of the chirp-ui component surface.

This module publishes the component registry (``chirp_ui.components.COMPONENTS``
plus ``chirp_ui.tokens.TOKEN_CATALOG``) as a stable JSON snapshot. AI agents
and docs tooling can read the manifest to cite real classes, tokens, slots,
and templates instead of plausible-sounding ones.

Schema
------
``{"schema": "chirpui-manifest@5", "version": "", "components": {...},
"tokens": {...}, "theme_packs": [...], "stats": {...}}``

* ``components`` keys sorted; each entry contains ``block``, ``variants``,
``sizes``, ``modifiers``, ``elements``, ``slots``, ``tokens``,
``extra_emits``, ``trim_emits``, ``emits``, ``template``, ``category``,
``maturity``, ``role``, ``authoring``, ``requires``, plus the ``@2``
additions ``macro``, ``params``, and ``lineno``, the ``@3`` composition
additions ``composes``, ``slot_forwards``, and ``slots_yielded``, and the
``@4`` appearance/tone additions ``appearances`` and ``tones``.
* ``params`` is a list of ``{"name": str, "has_default": bool,
"is_required": bool}`` derived from the template AST via
`chirp_ui._macro_introspect`. Empty when the descriptor has no
template, the macro cannot be resolved, or the template has no
``{% def %}`` matching the resolved name.
* ``macro`` is the resolved macro identifier (``descriptor.macro`` if set,
else ``block.replace("-", "_")``). ``null`` when the descriptor has no
template or no matching macro is found.
* ``lineno`` is the source line of the ``{% def %}`` tag (``0`` when
unavailable).
* ``slots`` is the sorted union of ``descriptor.slots``, direct slots
extracted from the macro body, and yielded slots accepted by composite
wrappers. The unnamed default slot is represented as ``""``. Hand-authored
descriptor entries can over-declare (e.g. for documentation), but the
manifest never under-reports a real slot.
* ``slots_extracted`` is the AST-derived slot list (sorted, default = ``""``)
exposed separately so parity tests can spot descriptor↔template drift
without losing the merged ``slots`` contract.
* ``slots_yielded`` is the source-derived list of ``{% yield %}`` /
``{% yield name %}`` caller slots. Composite forwarding metadata is explicit
in ``composes`` and ``slot_forwards``.
* ``provides`` / ``consumes`` are sorted lists of context keys (e.g.
``"_card_variant"``) sourced from `chirp_ui.inspect`. A key is
attributed to the macro whose ``{% def %}`` lineno is the largest one
preceding the ``{% provide %}`` / ``consume()`` site.
* ``description`` is the stripped text inside the leading
``{#- chirp-ui: ... -#}`` doc-block of the template file. One block per
file, covering every macro; empty string when the descriptor has no
template. New chirp-ui templates must carry a doc-block
(``tests/test_description_coverage.py``).
* ``tokens`` keys sorted; each entry is ``{"category": …, "scope": …}``.
* ``theme_packs`` lists packaged token-only theme CSS resources in stable
catalog order.
* ``stats`` aggregates counts, including ``components_with_params``, a
``registry_debt`` scorecard for descriptor/CSS reconciliation burn-down,
and a ``manifest_quality`` scorecard for agent-facing metadata coverage.

Deterministic: two calls to `build_manifest`() yield byte-identical JSON.

CLI
---
``python -m chirp_ui.manifest --json`` writes JSON to stdout.

See ``docs/plans/done/PLAN-agent-grounding-depth.md`` and
``docs/DESIGN-manifest-signature-extraction.md``.

_resolve_macro

function

Look up the ``MacroInfo`` for a descriptor, or ``None`` if unresolvable.

Resolution order: explicit ``descriptor.macro`` → ``block.replace("-", "_")``.
Returns ``None`` when the template is missing, the file has no defs, or
no def name matches the resolved macro identifier.

_runtime_requirements

function

Return sorted runtime requirements from descriptor + derived macro metadata.

_macro_source

function

Return the source slice for one macro body, bounded by the next ``{% def %}``.

_literal_attribute_names

function

Return literal HTML attribute names in a macro body using Kida analysis.

_manifest_quality

function

Return agent-facing metadata gap counts for public templated components.

_owning_macro

function

Return the macro name whose ``{% def %}`` lineno most-recently precedes ``line``.

Used to attribute a ``{% provide %}`` or ``consume()`` site (which has only
a template + line) to the macro it lives inside. Returns ``None`` if the
line is before any def (top-of-file noise).

_provide_consume_index

function

Index ``(template, macro_name) → (provides_keys, consumes_keys)``.

Built once per manifest; relies on the line-walked records from
`chirp_ui.inspect`. Templates with no defs (or sites before the
first def) are dropped silently.

build_manifest

function

Return the component/token manifest as a JSON-serializable dict.

Output is deterministic: components and tokens are sorted by key, and
every per-entry list (emits, variants, etc.) is sorted. Param order is
preserved as declared in the template (positional order matters for
macro callers).

to_json

function

Serialize a manifest to stable JSON (sort_keys, UTF-8, no trailing NL).

main

function