_macro_introspect
AST introspection for ``{% def %}`` macros — internal. Wraps `kida.lexer` + `kida.parser` to extract per-macro parameter metadata without compiling the template (so no chirp-ui filter stubs are required at manifest-build time). Used by `chirp_ui.manifest` to project macro Python signatures into the agent-groundable manifest. See ``docs/plans/done/PLAN-agent-grounding-depth.md`` and ``docs/DESIGN-manifest-signature-extraction.md``.
ParamInfo
Single ``{% def %}`` parameter, derived from the AST. ``has_default`` follows Python's trailing-defaults convention: kida's ``Def`` node parallels ``defaults`` to the last *N* of ``params``.
MacroInfo
Per-macro introspection result. ``slots`` is the tuple of ``{% slot name %}`` placeholders found in the macro body, in declaration order, deduplicated (a slot rendered twice appears once). The unnamed default slot is normalized from kida's ``"default"`` to ``""`` to match ``ComponentDescriptor.slots`` convention. ``yielded_slots`` is the tuple of ``{% yield %}`` / ``{% yield name %}`` caller slots accepted by composite macros and forwarded into child calls.
macros_in_template
Return ``{macro_name: MacroInfo}`` for every ``{% def %}`` in the template. Cached. Returns ``{}`` if the template file is missing or contains no defs. Template name is relative to ``src/chirp_ui/templates/chirpui/``.
_walk_slot_names
Yield public slot names reachable from ``node`` without crossing a nested ``Def``. chirp-ui currently has no nested defs (verified at Sprint 2), so this is defensive only — keeps slot ownership per-macro if that ever changes.
_yielded_slots_by_macro
Return ``macro_name → yielded slot names`` attributed by source line. The installed kida AST exposes ``Slot`` placeholders but not a public ``Yield`` node, so composite forwarded slots are found from the raw source and attributed to the nearest preceding ``{% def %}`` line. chirp-ui does not use nested defs, which keeps the ownership rule straightforward.
description_from_template
Return the leading ``{#- chirp-ui: ... -#}`` doc-block text, or ``""``. One doc-block per file, covering the file's entire set of macros — verified at Sprint 4 across all 195 chirp-ui templates. The block must appear before any ``{% def %}`` or ``{% from %}`` statement (the parser scans only the first ~2 KB to honor that invariant cheaply). Whitespace inside the block is preserved except for a single leading / trailing strip — so multi-line usage examples keep their shape. Inner indentation is left alone; downstream renderers (COMPONENT-OPTIONS generator, etc.) can post-process as needed.