Agentic-GenUI-Tools 0.2.0__py3-none-any.whl

adaptive_card_tools/builder.py

@@ -0,0 +1,1891 @@
+"""Forgiving element descriptions -> deterministic, styled Adaptive Cards 1.5.
+
+Pipeline: load (lenient JSON) -> document (unwrap, root fields) -> canonical
+nodes (type resolution/inference, field aliases) -> merge adjacent singles ->
+render with the theme -> width estimate. Every repair is recorded in metadata.
+"""
+from __future__ import annotations
+
+import json
+import math
+import re
+from dataclasses import dataclass, field
+
+from . import theme
+from .catalog import (CONTENT_KEYS, FIELD_ALIASES, SPECS, STYLE_KEYS, TYPE_KEYS, infer_type, map_fields, resolve_type)
+from .normalize import (WRAPPER_KEYS, BuilderConfig, CardError, Context, as_bool, as_date, as_id, as_number,
+                        as_time, as_url, clean_text, closest, display_text, format_number, is_slug_like,
+                        load_request, parse_json_text, parse_number, slug, submit_text, token)
+
+
+@dataclass
+class Node:
+    type: str
+    f: dict
+    path: str
+    hints: dict = field(default_factory=dict)
+    extras: list = field(default_factory=list)
+    unknown: list = field(default_factory=list)
+    source: str = ""
+
+
+def _keys(*names: str) -> set[str]:
+    return {token(n) for group in names for n in group.split()}
+
+
+def pick(obj: dict, keys: set[str]):
+    """First (key, value) whose key token is in keys."""
+    for k, v in obj.items():
+        if token(k) in keys and v is not None:
+            return k, v
+    return None, None
+
+
+def humanize(key: str) -> str:
+    if " " in key.strip() or not re.search(r"[_\-]|[a-z][A-Z]", key):
+        return key[:1].upper() + key[1:] if key[:1].islower() and " " not in key else key
+    words = re.sub(r"([a-z])([A-Z])", r"\1 \2", key).replace("_", " ").replace("-", " ").split()
+    return " ".join(words)[:1].upper() + " ".join(words)[1:].lower() if words else key
+
+
+ROOT_FIELDS = {
+    "title": _keys("title heading header card_title cardtitle headline"),
+    "subtitle": _keys("subtitle subheading subheader tagline byline"),
+    "status": _keys("status badge state"),
+    "elements": _keys("elements body items components questions fields children blocks sections widgets cards contents"),
+    "submit_label": _keys("submit_label submit_text submit_title submit_button button_text button_label submit"),
+    "buttons": _keys("buttons actions links ctas"),
+}
+ROOT_ALIAS = {t: name for name, tokens in ROOT_FIELDS.items() for t in tokens}
+LABEL_KEYS = _keys("title label text name display display_name caption option choice heading key fact property field attribute term metric kpi stat")
+VALUE_KEYS = _keys("value val id code data answer detail details content definition amount number figure count total score current current_value result y size")
+POINT_LABEL_KEYS = _keys("label name x category key title legend month date period year day week quarter group item time region product")
+SERIES_NAME_KEYS = _keys("name label legend title series key")
+SERIES_VALUE_KEYS = _keys("values data points y items")
+METRIC_MAP = {t: name for name, words in {
+    "label": "label title name metric kpi stat key caption heading",
+    "value": "value amount number figure count total score current current_value val result",
+    "change": "change delta diff difference trend growth variance pct_change percent_change movement change_percent",
+    "note": "note period context subtext secondary comparison target description subtitle footnote",
+    "lower_is_better": "lower_is_better good_direction inverse invert", "icon": "icon emoji"}.items() for t in _keys(words)}
+BUTTON_MAP = {t: name for name, words in {
+    "label": "label title text name caption", "url": "url href link uri target open_url openurl website destination",
+    "data": "data payload submit_data params parameters body value", "action": "action type kind on_click onclick click behavior action_type",
+    "style": "style tone variant color appearance intent importance priority", "icon": "icon emoji iconurl"}.items() for t in _keys(words)}
+TONE_WORDS = {
+    "danger": "danger error red critical bad negative failed fail failure rejected blocked overdue urgent offline down outage cancelled canceled lost expired declined denied breach destructive alert attention offtrack",
+    "warning": "warning warn yellow orange amber caution pending review inreview awaiting waiting atrisk risk degraded delayed partial expiring due onhold hold behind",
+    "success": "success successful good green positive ok okay done complete completed approved active passed pass paid resolved shipped delivered live healthy online available enabled won confirmed accepted ontrack ahead",
+    "info": "info information informative blue accent primary new inprogress progress open running scheduled planned processing started ongoing",
+    "neutral": "neutral default gray grey secondary muted subtle closed archived draft inactive paused none unknown notstarted",
+}
+TONE_LOOKUP = {w: tone for tone, words in TONE_WORDS.items() for w in words.split()}
+TONE_NAMES = _keys("success successful good warning warn danger error info information informative neutral default red green "
+                   "yellow orange amber blue gray grey accent attention positive negative critical primary secondary muted subtle")
+SUBMIT_WORDS = _keys("submit actionsubmit execute actionexecute postback imback messageback send save")
+LINK_WORDS = _keys("openurl actionopenurl link url navigate open href redirect website")
+NUMERIC_CELL = re.compile(r"[(~+\-−]?\s*[$€£¥₹]?\s*\d[\d.,' ]*\s*(%|[kKmMbB]n?|[A-Za-z]{1,3})?\)?")
+MIME = {".mp4": "video/mp4", ".m4v": "video/mp4", ".mov": "video/quicktime", ".webm": "video/webm",
+        ".mp3": "audio/mpeg", ".wav": "audio/wav", ".ogg": "audio/ogg", ".m4a": "audio/mp4", ".aac": "audio/aac"}
+
+
+def tone_of(value, fallback_text: str = "") -> str:
+    for candidate in (value, fallback_text):
+        if isinstance(candidate, str) and candidate.strip():
+            t = token(candidate)
+            if t in TONE_LOOKUP:
+                return TONE_LOOKUP[t]
+            words = [token(w) for w in re.findall(r"[A-Za-z]+", candidate)]
+            for tone in ("danger", "warning", "success", "info"):
+                if any(TONE_LOOKUP.get(w) == tone for w in words):
+                    return tone
+    return "neutral"
+
+
+def _is_input(card_element: dict) -> bool:
+    return str(card_element.get("type", "")).startswith("Input.")
+
+
+class CardBuilder:
+    def __init__(self, config: BuilderConfig):
+        self.config = config
+        self.ctx = Context(config)
+        self.input_ids: list[str] = []
+        self.used_ids: set[str] = set()
+        self.reserved_ids: set[str] = set()
+        self.choice_values: dict[str, list[dict]] = {}
+        self.element_count = 0
+        self.column_depth = 0
+        self.min_width, self.floor_percent, self.force_overflow = 320, 50, False
+        self.width_reasons: list[str] = []
+
+    # ------------------------------------------------------------ helpers
+
+    @property
+    def native(self) -> bool:
+        return self.config.profile == "microsoft"
+
+    def native_ok(self, name: str) -> bool:
+        return self.native and (self.config.native_types is None or name in self.config.native_types)
+
+    def extension(self, native: dict, fallback: dict, path: str) -> dict:
+        if self.native_ok(native["type"]):
+            return {**native, "fallback": fallback}
+        return fallback
+
+    def need(self, pixels: int, percent: int, reason: str, *, overflow=False):
+        self.min_width = max(self.min_width, pixels)
+        self.floor_percent = max(self.floor_percent, percent)
+        self.force_overflow |= overflow
+        if reason not in self.width_reasons:
+            self.width_reasons.append(reason)
+
+    def title_prefix(self, node: Node) -> list[dict]:
+        title = clean_text(node.f.get("title"))
+        return [theme.group_title(self.with_icon(title, node))] if title else []
+
+    def with_icon(self, text: str, node: Node) -> str:
+        icon = node.hints.get("icon")
+        if isinstance(icon, str) and 0 < len(icon.strip()) <= 4 and not icon.strip().isascii():
+            return f"{icon.strip()} {text}"
+        return text
+
+    # ------------------------------------------------------------ document
+
+    def unwrap(self, raw, path="$"):
+        for _ in range(5):
+            if isinstance(raw, str) and raw.strip()[:1] in "[{":
+                raw = parse_json_text(raw, self.ctx, path)
+                continue
+            if isinstance(raw, dict):
+                keys = {token(k): k for k in raw}
+                carrier = next((keys[t] for t in ("arguments", "args", "parameters", "params", "input") if t in keys), None)
+                if carrier and set(keys) - {token(carrier)} <= {"name", "tool", "function", "id", "toolname", "type"}:
+                    raw = raw[carrier]
+                    self.ctx.fixed(path, "unwrapped_tool_call", key=carrier)
+                    continue
+                if len(raw) == 1:
+                    (k, v), = raw.items()
+                    if token(k) in WRAPPER_KEYS and (isinstance(v, (dict, list)) or isinstance(v, str) and v.strip()[:1] in "[{"):
+                        raw = v
+                        self.ctx.fixed(path, "unwrapped", key=k)
+                        continue
+            break
+        return raw
+
+    def document(self, raw) -> dict:
+        raw = self.unwrap(raw)
+        if isinstance(raw, list):
+            return {"elements": raw}
+        if not isinstance(raw, dict):
+            return {"elements": [raw]}
+        type_key = next((k for k in raw if token(k) in TYPE_KEYS and isinstance(raw[k], str)), None)
+        if type_key is not None:
+            resolved = resolve_type(raw[type_key], Context(self.config), "$." + type_key)
+            if resolved and resolved[0] in {"document", "section"}:
+                self.ctx.fixed("$." + type_key, "type_alias", source=raw[type_key], target="document")
+                return self.root_fields({k: v for k, v in raw.items() if k != type_key})
+            if resolved or not any(token(k) in ROOT_FIELDS["elements"] for k in raw):
+                return self.single_element(raw, resolved[0] if resolved else None)
+        elements_key = next((k for k, v in raw.items() if token(k) in ROOT_FIELDS["elements"] and isinstance(v, (list, dict)) and v), None)
+        if elements_key and not (token(elements_key) == "items" and isinstance(raw[elements_key], list)
+                                 and all(isinstance(i, (str, int, float)) for i in raw[elements_key])):
+            return self.root_fields(raw)
+        inferred = infer_type(raw)
+        if inferred and inferred[0] not in {"text", "heading", "section"}:
+            # Only a single element if every key belongs to it (or to the card header).
+            own = FIELD_ALIASES[inferred[0]]
+            if all(token(k) in own or token(k) in ROOT_ALIAS and ROOT_ALIAS[token(k)] != "elements" or token(k) in STYLE_KEYS for k in raw):
+                return self.single_element(raw, inferred[0])
+        return self.root_fields(raw)
+
+    def single_element(self, raw: dict, canonical: str | None) -> dict:
+        """A lone element sent as the whole request; card-level keys move to the card."""
+        doc = {"elements": []}
+        element = {}
+        spec = SPECS.get(canonical) if canonical else None
+        label_like = sum(1 for k in raw if token(k) in _keys("label question prompt text"))
+        for k, v in raw.items():
+            field = ROOT_ALIAS.get(token(k))
+            if field in {"subtitle", "submit_label"} or (field == "status" and canonical != "badge"):
+                doc[field] = v
+            elif token(k) == "title" and spec and "title" not in doc and (
+                    spec.kind == "display" and canonical not in {"text", "heading", "note", "badge"}
+                    or spec.kind == "input" and label_like):
+                doc["title"] = v
+            else:
+                element[k] = v
+        doc["elements"].append(element)
+        return doc
+
+    def root_fields(self, raw: dict) -> dict:
+        doc = {"elements": []}
+        pending_facts: dict = {}
+
+        def flush():
+            if pending_facts:
+                doc["elements"].append({"type": "facts", "facts": dict(pending_facts)})
+                pending_facts.clear()
+
+        for key, value in raw.items():
+            t = token(key)
+            field = ROOT_ALIAS.get(t)
+            if field is None and t not in STYLE_KEYS and t not in {"schema", "version", "type"}:
+                near = closest(t, ROOT_ALIAS, self.ctx)
+                field = ROOT_ALIAS.get(near) if near and len(t) >= 6 else None
+            if field == "buttons" and value == []:
+                doc.setdefault("buttons", [])
+                continue
+            if field is not None and field != "elements" and value in (None, "", [], {}):
+                continue
+            if field == "elements":
+                flush()
+                if isinstance(value, dict):
+                    value = list(value.values()) if all(isinstance(v, dict) for v in value.values()) else [value]
+                doc["elements"].extend(value if isinstance(value, list) else [value])
+            elif field == "buttons" or (field == "submit_label" and isinstance(value, (dict, list))):
+                doc.setdefault("buttons", []).extend(value if isinstance(value, list) else [value])
+            elif field in {"title", "subtitle", "status", "submit_label"}:
+                if field in doc:
+                    doc["elements"].append({"type": "text", "text": display_text(value)})
+                else:
+                    doc[field] = value
+            elif t in STYLE_KEYS or t in {"schema", "version", "type", "id"}:
+                self.ctx.fixed("$." + key, "ignored_style_key")
+            else:
+                # A root key named after an element: {"chart": {...}}, {"footer": "..."}, {"logo": "https://..."}.
+                resolved = resolve_type(key, Context(self.config), "$." + key)
+                scalar = isinstance(value, (str, int, float, bool))
+                if resolved and resolved[0] not in {"document", "column"} and not (scalar and SPECS[resolved[0]].kind == "input"):
+                    flush()
+                    canonical = resolved[0]
+                    flat = isinstance(value, dict) and all(not isinstance(v, (dict, list)) for v in value.values())
+                    if isinstance(value, dict) and any(token(k) in TYPE_KEYS for k in value):
+                        element = value
+                    elif isinstance(value, dict) and not (flat and canonical in {"facts", "chart", "metrics", "table"}):
+                        element = {"type": key, **value}
+                    else:
+                        element = {"type": key, SPECS[canonical].main or "text": value}
+                    doc["elements"].append(element)
+                    self.ctx.fixed("$." + key, "root_key_as_element", target=canonical)
+                elif scalar or (isinstance(value, list) and all(isinstance(v, (str, int, float)) for v in value)):
+                    pending_facts[humanize(key)] = value
+                    self.ctx.fixed("$." + key, "root_value_as_fact")
+                elif isinstance(value, (dict, list)) and value:
+                    flush()
+                    doc["elements"].append(value if isinstance(value, dict) else {"type": "section", "elements": value})
+                    self.ctx.fixed("$." + key, "root_key_as_element")
+        flush()
+        return doc
+
+    # ------------------------------------------------------------ canonical nodes
+
+    def canonicalize(self, raw, path: str) -> list[Node]:
+        if raw is None or raw == "" or raw == {} or raw == []:
+            return []
+        if isinstance(raw, (str, int, float, bool)):
+            return self.markdown_nodes(display_text(raw), path)
+        if isinstance(raw, list):
+            return [Node("section", {"elements": raw}, path)]
+        type_keys = [k for k in raw if token(k) in TYPE_KEYS and isinstance(raw[k], str)]
+        type_keys.sort(key=lambda k: token(k) != "type")
+        resolved, source = None, ""
+        for k in type_keys:
+            resolved = resolve_type(raw[k], self.ctx, f"{path}.{k}")
+            source = token(raw[k])
+            if resolved:
+                break
+        if not resolved:
+            resolved = infer_type({k: v for k, v in raw.items() if k not in type_keys})
+            if resolved and type_keys:
+                self.ctx.warn(path, "unknown_type", f"Unknown type '{raw[type_keys[0]]}'; shown as {resolved[0]} based on its fields.")
+            elif resolved:
+                self.ctx.fixed(path, "type_inferred", target=resolved[0])
+        if not resolved:
+            texts = [clean_text(v) for k, v in raw.items()
+                     if k not in type_keys and (token(k) in CONTENT_KEYS or token(k) in {"title", "label", "name", "value"})]
+            texts = [t for t in texts if t]
+            if texts:
+                self.ctx.warn(path, "unknown_element", "Could not tell what this element is; its text is shown as a paragraph.")
+                return [Node("text", {"text": "\n\n".join(texts)}, path)]
+            self.ctx.warn(path, "dropped_element", "Could not tell what this element is, so it was left out.")
+            return []
+        canonical, implied = resolved
+        canonical, implied = self.refine(canonical, dict(implied), raw, source)
+        if canonical == "document":
+            inner = self.root_fields({k: v for k, v in raw.items() if k not in type_keys})
+            title = inner.get("title")
+            return [Node("section", {"title": title, "elements": inner["elements"] + ([{"type": "buttons", "buttons": inner["buttons"]}] if inner.get("buttons") else [])}, path)]
+        fields = map_fields(canonical, raw, path, self.ctx, skip=type_keys)
+        values = {**implied, **fields.values}
+        return [Node(canonical, values, path, fields.hints, fields.extras, fields.unknown, source)]
+
+    def refine(self, canonical: str, implied: dict, raw: dict, source: str) -> tuple[str, dict]:
+        """Correct a type using the fields that are actually present."""
+        keys = {token(k) for k in raw}
+        kind = SPECS[canonical].kind
+        if kind == "input" and canonical != "choice" and keys & {"options", "choices"}:
+            return "choice", ({"multiple": True} if canonical == "checkbox" else {})
+        if canonical in {"text", "note", "heading"}:
+            has_text = keys & {"text", "content", "body", "value", "message", "paragraph", "markdown"}
+            if not has_text and keys & {"placeholder", "required", "isrequired", "maxlength", "multiline", "ismultiline"}:
+                return "text_input", {}
+            if not has_text and "items" in keys:
+                return "list", implied
+        if canonical == "chart" and not keys & {"data", "series", "datasets", "values", "value", "points"} and keys & {"rows", "records"}:
+            return "table", {}
+        if canonical in {"columns", "list", "facts"} and "rows" in keys and canonical != "facts":
+            return "table", {}
+        if canonical == "table" and "columns" in keys and not keys & {"rows", "data", "records", "items", "entries"}:
+            return "columns", {}
+        if canonical == "image" and keys & {"images", "urls", "gallery"}:
+            return "images", {}
+        if canonical == "section" and "columns" in keys and not keys & {"elements", "items", "body", "children"}:
+            return "columns", {}
+        if canonical == "chart" and source == "line" and not keys & {"data", "series", "datasets", "values", "points", "value"}:
+            return "divider", {}
+        return canonical, implied
+
+    def markdown_nodes(self, text: str, path: str) -> list[Node]:
+        """Split markdown-ish text into headings, lists, tables and paragraphs."""
+        if "\n" not in text and not re.match(r"\s*#{1,6}\s", text):
+            return [Node("text", {"text": text}, path)]
+        nodes, para, bullets, numbered, table_lines = [], [], [], False, []
+
+        def flush_para():
+            if para:
+                joined = "\n".join(para).strip()
+                if joined:
+                    nodes.append(Node("text", {"text": joined}, path))
+                para.clear()
+
+        def flush_list():
+            nonlocal numbered
+            if bullets:
+                nodes.append(Node("list", {"items": list(bullets), "numbered": numbered}, path))
+                bullets.clear()
+            numbered = False
+
+        def flush_table():
+            if table_lines:
+                rows = [[c.strip() for c in line.strip().strip("|").split("|")] for line in table_lines
+                        if not re.fullmatch(r"\s*\|?\s*:?-{2,}:?\s*(\|\s*:?-{2,}:?\s*)*\|?\s*", line)]
+                if len(rows) >= 2:
+                    nodes.append(Node("table", {"columns": rows[0], "rows": rows[1:]}, path))
+                else:
+                    para.extend(table_lines)
+                table_lines.clear()
+
+        for line in text.splitlines():
+            heading = re.match(r"\s*#{1,6}\s+(.*)", line)
+            bullet = re.match(r"\s*[-*•]\s+(.*)", line)
+            number = re.match(r"\s*\d{1,3}[.)]\s+(.*)", line)
+            if line.strip().startswith("|") and line.count("|") >= 2:
+                flush_para(), flush_list()
+                table_lines.append(line)
+                continue
+            flush_table()
+            if heading:
+                flush_para(), flush_list()
+                nodes.append(Node("heading", {"text": heading.group(1).strip().strip("#").strip()}, path))
+            elif bullet or number:
+                flush_para()
+                if bullets and bool(number) != numbered:
+                    flush_list()
+                numbered = bool(number)
+                bullets.append((bullet or number).group(1))
+            elif not line.strip():
+                flush_para(), flush_list()
+            else:
+                flush_list()
+                para.append(line)
+        flush_table(), flush_para(), flush_list()
+        if len(nodes) > 1 or (nodes and nodes[0].type != "text"):
+            self.ctx.fixed(path, "markdown_structure")
+        return nodes
+
+    def merge(self, nodes: list[Node]) -> list[Node]:
+        """Combine adjacent single metrics, buttons, badges and columns into one row."""
+        out: list[Node] = []
+        for node in nodes:
+            prev = out[-1] if out else None
+            if node.type == "metrics" and "items" not in node.f:
+                single = dict(node.f)
+                if "label" not in single and "title" in single:
+                    single["label"] = single.pop("title")
+                single.pop("title", None)
+                if "icon" in node.hints:
+                    single["icon"] = node.hints["icon"]
+                node.f = {"items": [single], "_single": True}
+            if node.type == "column":
+                node = Node("columns", {"columns": [{"title": node.f.get("title"), "elements": node.f.get("elements", [])}], "_single": True}, node.path)
+            if prev and prev.type == node.type and prev.f.get("_single") and node.f.get("_single") and "title" not in node.f:
+                if node.type == "metrics":
+                    prev.f["items"].extend(node.f["items"])
+                    continue
+                if node.type == "columns":
+                    prev.f["columns"].extend(node.f["columns"])
+                    continue
+            if prev and node.type == "buttons" and prev.type == "buttons" and not node.extras and not prev.extras:
+                prev.f.setdefault("_merged", []).append(node)
+                continue
+            if prev and node.type == "badge" and prev.type == "badge" and not node.extras and not prev.extras:
+                prev.f.setdefault("_merged", []).append(node)
+                continue
+            out.append(node)
+        for node in out:
+            if node.type == "columns" and node.f.get("_single") and len(node.f["columns"]) == 1:
+                node.type, node.f = "section", {"title": node.f["columns"][0].get("title"), "elements": node.f["columns"][0].get("elements", [])}
+        return out
+
+    # ------------------------------------------------------------ rendering
+
+    def render_list(self, raw_items, path: str, depth: int) -> list[dict]:
+        if depth > self.config.max_depth:
+            raise CardError(path, "Nesting limit exceeded.", "limit_exceeded")
+        if isinstance(raw_items, dict):
+            raw_items = [raw_items]
+        elif not isinstance(raw_items, list):
+            raw_items = [raw_items]
+        nodes = []
+        for i, item in enumerate(raw_items):
+            nodes.extend(self.canonicalize(item, f"{path}[{i}]"))
+        out: list[dict] = []
+        divider = False
+        for node in self.merge(nodes):
+            if node.type == "divider":
+                divider = bool(out)
+                continue
+            rendered = self.render(node, depth)
+            if rendered and divider:
+                rendered[0] = {**rendered[0], "separator": True, "spacing": "Large"}
+            divider = divider and not rendered
+            out.extend(rendered)
+        return out
+
+    def render(self, node: Node, depth: int) -> list[dict]:
+        self.element_count += 1
+        if self.element_count > self.config.max_elements:
+            raise CardError(node.path, f"More than {self.config.max_elements} elements; split the content into several cards.", "limit_exceeded")
+        out = getattr(self, "r_" + node.type)(node, depth)
+        if out:
+            out.extend(self.extra_blocks(node))
+        for key, _ in node.unknown:
+            self.ctx.warn(f"{node.path}.{key}", "ignored_field", f"Field '{key}' is not used by {node.type} and was left out.")
+        return out
+
+    def extra_blocks(self, node: Node) -> list[dict]:
+        blocks = []
+        for key, value in node.extras:
+            content = clean_text(value)
+            if not content:
+                continue
+            long_form = token(key) in _keys("description desc body content message text details detail summary explanation context instructions")
+            blocks.append(theme.body(content) if long_form or len(content) > 160 else theme.note(content))
+            self.ctx.fixed(f"{node.path}.{key}", "shown_as_text")
+        if blocks and node.type in {"heading"}:
+            blocks[0] = {**blocks[0], "spacing": "None"}
+        return blocks
+
+    def text_of(self, node: Node, *fallbacks: str) -> str:
+        for name in ("text", *fallbacks):
+            value = node.f.get(name)
+            if isinstance(value, list) and value and all(isinstance(v, dict) for v in value):
+                # RichTextBlock inlines / TextRuns.
+                runs = []
+                for run in value:
+                    _, piece = pick(run, _keys("text content value"))
+                    piece = display_text(piece)
+                    bold = token(run.get("weight", "")) == "bolder" and piece.strip()
+                    runs.append(f"**{piece}**" if bold else piece)
+                value = "".join(runs)
+            value = clean_text(value)
+            if value:
+                return value
+        if node.extras:
+            key, value = node.extras.pop(0)
+            return clean_text(value)
+        return ""
+
+    def r_heading(self, node: Node, depth: int) -> list[dict]:
+        content = self.text_of(node, "title", "label")
+        if not content:
+            self.ctx.warn(node.path, "empty_element", "Heading had no text and was left out.")
+            return []
+        return [theme.spaced(theme.heading(self.with_icon(content, node)), "Large")]
+
+    def r_text(self, node: Node, depth: int) -> list[dict]:
+        title = clean_text(node.f.get("title"))
+        content = self.text_of(node, "label")
+        if not content:
+            if title:
+                return [theme.body(title)]
+            self.ctx.warn(node.path, "empty_element", "Text element had no text and was left out.")
+            return []
+        prefix = [theme.group_title(title)] if title else []
+        size, weight = token(node.hints.get("size", "")), token(node.hints.get("weight", ""))
+        if "\n" in content and re.search(r"(^|\n)\s*(#{1,6}\s|\|.*\|)", content):
+            parts = self.markdown_nodes(content, node.path)
+            return prefix + [b for part in parts for b in self.render(part, depth)]
+        if (size in {"large", "extralarge", "xl", "xxl", "big", "huge", "medium"} or weight in {"bolder", "bold"}
+                or node.hints.get("style") == "heading" or node.source in {"h1", "h2", "h3"}) and len(content) <= 120 and "\n" not in content:
+            self.ctx.fixed(node.path, "styled_text_as_heading")
+            return prefix + [theme.spaced(theme.heading(self.with_icon(content, node)), "Large")]
+        if size in {"small", "tiny", "xs"} or as_bool(node.hints.get("issubtle"), False) or token(node.hints.get("color", "")) in {"gray", "grey", "muted", "subtle", "secondary"}:
+            return prefix + [theme.note(content)]
+        self.need(min(640, max(320, len(content) * 4)), 50, "Text wraps within the card.")
+        return prefix + [theme.body(self.with_icon(content, node))]
+
+    def r_note(self, node: Node, depth: int) -> list[dict]:
+        content = self.text_of(node, "title", "label")
+        return [theme.note(content)] if content else []
+
+    # -- lists, facts, tables
+
+    def list_items(self, raw) -> list[str]:
+        if isinstance(raw, str):
+            raw = [line for line in raw.splitlines() if line.strip()] if "\n" in raw else [raw]
+        if isinstance(raw, dict):
+            return [f"**{k}**: {display_text(v)}" for k, v in raw.items()]
+        items = []
+        for item in raw if isinstance(raw, list) else [raw]:
+            if isinstance(item, dict):
+                _, head = pick(item, _keys("title label name heading text"))
+                _, detail = pick(item, _keys("description detail details text body value summary"))
+                if head is not None and detail is not None and head is not detail:
+                    items.append(f"**{display_text(head)}**: {display_text(detail)}")
+                    continue
+                item = head if head is not None else detail if detail is not None else item
+            text = clean_text(item)
+            if text:
+                items.append(text)
+        return items
+
+    def r_list(self, node: Node, depth: int) -> list[dict]:
+        items = self.list_items(node.f.get("items", []))
+        if not items:
+            self.ctx.warn(node.path, "empty_element", "List had no items and was left out.")
+            return []
+        numbered = as_bool(node.f.get("numbered"), False)
+        stripped = [re.sub(r"^\s*(?:[-*•]|\d{1,3}[.)])\s+", "", i) for i in items]
+        if stripped != items:
+            numbered = numbered or all(re.match(r"^\s*\d{1,3}[.)]\s", i) for i in items)
+            self.ctx.fixed(node.path, "removed_list_markers")
+        width = 12 if not numbered else 20 if len(stripped) < 10 else 28
+        rows = [theme.bullet_row(f"{i}." if numbered else "•", item, width) for i, item in enumerate(stripped, 1)]
+        rows[0] = {**rows[0], "spacing": "Default"}
+        self.need(min(680, max(320, max(len(i) for i in stripped) * 4)), 50, "Text wraps within the card.")
+        return self.title_prefix(node) + rows
+
+    def fact_pairs(self, raw, path: str) -> list[tuple[str, str]] | None:
+        """Label/value pairs from many shapes. None means 'this is really a table'."""
+        if isinstance(raw, str):
+            raw = [line for line in raw.splitlines() if line.strip()]
+        pairs = []
+        if isinstance(raw, dict):
+            for k, v in raw.items():
+                pairs.append((display_text(k), clean_text(v)))
+            return pairs
+        if not isinstance(raw, list):
+            return [("", clean_text(raw))]
+        dict_items = [i for i in raw if isinstance(i, dict)]
+        if dict_items and len(dict_items) == len(raw) and len(raw) > 1:
+            shared = set(dict_items[0])
+            if len(shared) >= 2 and all(set(d) == shared for d in dict_items) and not {token(k) for k in shared} & LABEL_KEYS:
+                return None
+        for item in raw:
+            if isinstance(item, dict):
+                if len(item) == 1:
+                    (k, v), = item.items()
+                    pairs.append((display_text(k), clean_text(v)))
+                    continue
+                lk, label = pick(item, LABEL_KEYS)
+                rest = {k: v for k, v in item.items() if k != lk}
+                vk, value = pick(rest, VALUE_KEYS)
+                if label is not None and vk is not None:
+                    pairs.append((display_text(label), clean_text(value)))
+                else:
+                    pairs.extend((humanize(k), clean_text(v)) for k, v in item.items())
+            elif isinstance(item, list) and len(item) == 2:
+                pairs.append((display_text(item[0]), clean_text(item[1])))
+            else:
+                text = clean_text(item)
+                m = re.match(r"\s*([^:=\t]{1,80}?)\s*(?::|=|\t| - | – )\s*(.+)", text, re.S)
+                pairs.append((m.group(1), m.group(2)) if m else ("", text))
+        return pairs
+
+    def r_facts(self, node: Node, depth: int) -> list[dict]:
+        raw = node.f.get("facts")
+        inline = [(humanize(k), clean_text(v)) for k, v in node.unknown if not isinstance(v, (dict, list))]
+        if inline:
+            # {"type": "facts", "Owner": "Dana"}: extra scalar keys on a facts element are facts.
+            node.unknown = [(k, v) for k, v in node.unknown if isinstance(v, (dict, list))]
+            self.ctx.fixed(node.path, "fields_as_facts")
+        pairs = self.fact_pairs(raw, node.path) if raw is not None else []
+        if pairs is not None:
+            pairs = pairs + inline
+        if pairs is None:
+            self.ctx.fixed(node.path, "facts_as_table")
+            return self.r_table(Node("table", {"rows": raw, "title": node.f.get("title")}, node.path), depth)
+        if pairs and all(not label for label, _ in pairs):
+            return self.r_list(Node("list", {"items": [v for _, v in pairs], "title": node.f.get("title")}, node.path), depth)
+        pairs = [(label, value or "—") for label, value in pairs if label or value]
+        if not pairs:
+            self.ctx.warn(node.path, "empty_element", "Facts had no entries and were left out.")
+            return []
+        longest = max(len(a) + len(b) for a, b in pairs)
+        self.need(min(720, max(400, longest * 7)), 50, "Fact labels and values share a row.")
+        return self.title_prefix(node) + [theme.spaced({"type": "FactSet", "facts": [{"title": a, "value": b} for a, b in pairs]}, "Small")]
+
+    def cell_text(self, cell) -> str:
+        if isinstance(cell, dict):
+            items = next((v for k, v in cell.items() if token(k) in {"items", "elements", "content"}), None)
+            if isinstance(items, list):
+                return " ".join(clean_text(self.cell_text(i)) for i in items).strip() or "—"
+            _, value = pick(cell, _keys("text value title label"))
+            if value is not None:
+                return clean_text(value) or "—"
+        return clean_text(cell) or "—"
+
+    def table_data(self, node: Node):
+        rows = node.f.get("rows")
+        columns = node.f.get("columns")
+        header_labels = {}
+        if isinstance(columns, str):
+            columns = [c.strip() for c in re.split(r"[,|]", columns) if c.strip()]
+        if isinstance(columns, list):
+            normalized = []
+            for c in columns:
+                if isinstance(c, dict):
+                    kk, key = pick(c, _keys("key field id name accessor datakey data_index"))
+                    _, label = pick(c, _keys("title label header heading text display"))
+                    key = display_text(key if key is not None else label)
+                    header_labels[key] = display_text(label if label is not None else key)
+                    normalized.append(key)
+                else:
+                    normalized.append(display_text(c))
+            columns = normalized
+        elif columns is not None:
+            columns = None
+        if isinstance(rows, str):
+            rows = [[c.strip() for c in re.split(r"\t|\|", line) if c.strip()] for line in rows.splitlines() if line.strip()]
+        if isinstance(rows, dict):
+            values = list(rows.values())
+            if values and all(isinstance(v, list) for v in values) and len({len(v) for v in values}) == 1:
+                columns = columns or list(rows)
+                rows = [dict(zip(rows, r)) for r in zip(*values)]
+                self.ctx.fixed(node.path, "columnar_table_transposed")
+            elif values and all(isinstance(v, dict) for v in values):
+                rows = [{"Item": k, **v} for k, v in rows.items()]
+                self.ctx.fixed(node.path, "keyed_rows")
+            else:
+                rows = [{"Item": k, "Value": v} for k, v in rows.items()]
+        if not isinstance(rows, list) or not rows:
+            return None, None
+        if all(isinstance(r, dict) and any(token(k) == "cells" for k in r) for r in rows):
+            rows = [[self.cell_text(c) for c in next(v for k, v in r.items() if token(k) == "cells")] for r in rows]
+            if columns is None and len(rows) > 1 and as_bool(node.hints.get("firstrowasheader"), True):
+                columns, rows = rows[0], rows[1:]
+        if all(isinstance(r, dict) for r in rows):
+            keys = list(dict.fromkeys(k for r in rows for k in r))
+            headers = list(columns or []) + [k for k in keys if k not in (columns or [])]
+            data = [[self.cell_text(r.get(h)) for h in headers] for r in rows]
+        elif all(isinstance(r, list) for r in rows):
+            width = max(len(r) for r in rows)
+            if columns is None:
+                if len(rows) > 1 and all(isinstance(v, str) for v in rows[0]) and len(rows[0]) == width:
+                    columns, rows = rows[0], rows[1:]
+                    self.ctx.fixed(node.path, "first_row_as_header")
+                else:
+                    columns = []
+            headers = list(columns) + [f"Column {i + 1}" for i in range(len(columns), width)]
+            data = [[self.cell_text(v) for v in r] + ["—"] * (len(headers) - len(r)) for r in rows]
+            if any(len(r) != width for r in rows):
+                self.ctx.fixed(node.path, "padded_short_rows")
+        else:
+            if all(not isinstance(r, (dict, list)) for r in rows):
+                return "list", rows
+            headers = list(columns or ["Value"])
+            data = [[self.cell_text(r)] if not isinstance(r, list) else [self.cell_text(v) for v in r] for r in rows]
+            width = max(len(r) for r in data)
+            headers += [f"Column {i + 1}" for i in range(len(headers), width)]
+            data = [r + ["—"] * (len(headers) - len(r)) for r in data]
+        headers = [header_labels.get(h, humanize(display_text(h)) if isinstance(h, str) and "_" in h else display_text(h)) or "—" for h in headers]
+        return headers, data
+
+    def r_table(self, node: Node, depth: int) -> list[dict]:
+        headers, data = self.table_data(node)
+        if headers == "list":
+            return self.r_list(Node("list", {"items": data, "title": node.f.get("title")}, node.path), depth)
+        if not headers or not data:
+            self.ctx.warn(node.path, "empty_element", "Table had no rows and was left out.")
+            return []
+        numeric = [all(NUMERIC_CELL.fullmatch(r[i].strip()) for r in data if r[i] != "—") and any(r[i] != "—" for r in data)
+                   for i in range(len(headers))]
+        lengths = [max(len(h), *(len(r[i]) for r in data)) for i, h in enumerate(headers)]
+        weights = [max(1, min(4, math.ceil(n / 12))) for n in lengths]
+        sizes = [max(96, min(240, n * 7 + 24)) for n in lengths]
+        self.need(sum(sizes) + 32, 50 if len(headers) <= 3 else 80 if len(headers) <= 5 else 100,
+                  "Tables need enough width for each column; cell text wraps.")
+        return self.title_prefix(node) + [theme.spaced(theme.table(headers, data, numeric, weights), "Small")]
+
+    # -- metrics, badges, progress, ratings
+
+    def metric_items(self, raw) -> list[dict]:
+        items = []
+        if isinstance(raw, dict):
+            raw = [{"label": k, **(v if isinstance(v, dict) else {"value": v})} for k, v in raw.items()]
+        for item in raw if isinstance(raw, list) else [raw]:
+            if isinstance(item, str):
+                m = re.match(r"\s*(.+?)\s*[:=]\s*(.+)", item)
+                item = {"label": m.group(1), "value": m.group(2)} if m else {"value": item}
+            if not isinstance(item, dict):
+                item = {"value": item}
+            mapped = {}
+            for k, v in item.items():
+                name = METRIC_MAP.get(token(k))
+                if name and name not in mapped:
+                    mapped[name] = v
+                elif not name and len(item) == 1:
+                    mapped = {"label": k, "value": v}
+            items.append(mapped)
+        return items
+
+    def r_metrics(self, node: Node, depth: int) -> list[dict]:
+        items = self.metric_items(node.f.get("items", []))
+        tiles = []
+        for i, item in enumerate(items):
+            value = clean_text(item.get("value"))
+            label = clean_text(item.get("label"))
+            if not value and not label:
+                continue
+            change = clean_text(item.get("change"))
+            color = "Default"
+            if change:
+                direction = self.change_direction(change)
+                if direction:
+                    lower_better = item.get("lower_is_better")
+                    good = direction > 0
+                    if as_bool(lower_better, False) or token(lower_better or "") in {"down", "lower", "decrease"}:
+                        good = not good
+                    color = "Good" if good else "Attention"
+                    if not re.match(r"\s*[▲▼↑↓⬆⬇]", change):
+                        change = f"{'▲' if direction > 0 else '▼'} {change.strip()}"
+            icon = item.get("icon")
+            if isinstance(icon, str) and 0 < len(icon.strip()) <= 4 and not icon.isascii():
+                label = f"{icon.strip()} {label}"
+            tiles.append(theme.metric_tile(label or " ", value or "—", change or None, color, clean_text(item.get("note")) or None))
+        if not tiles:
+            self.ctx.warn(node.path, "empty_element", "Metrics had no values and were left out.")
+            return []
+        per_row = min(4, len(tiles))
+        rows_needed = math.ceil(len(tiles) / per_row)
+        per_row = math.ceil(len(tiles) / rows_needed)
+        rows = [theme.row(*tiles[i:i + per_row], spacing="Medium") for i in range(0, len(tiles), per_row)]
+        self.need(min(1100, 200 * per_row + 40), 50 if per_row <= 2 else 60 if per_row == 3 else 80, "Metric tiles sit side by side.")
+        return self.title_prefix(node) + rows
+
+    @staticmethod
+    def change_direction(change: str) -> int:
+        t = change.strip()
+        if re.match(r"[+▲↑⬆]|up\b|increase|rise|higher|grew|gain", t, re.I):
+            return 1
+        if re.match(r"[-−–▼↓⬇]|down\b|decrease|drop|fall|lower|declin|loss", t, re.I):
+            return -1
+        number = as_number(t)
+        return 0 if not number else (1 if number > 0 else -1)
+
+    def badge_element(self, text: str, tone: str, path: str) -> dict:
+        _, style, _ = theme.TONES[tone]
+        return self.extension({"type": "Badge", "text": text, "style": style, "appearance": "tint"}, theme.badge(text, tone), path)
+
+    def r_badge(self, node: Node, depth: int) -> list[dict]:
+        badges = []
+        for item in [node, *node.f.get("_merged", [])]:
+            text = self.text_of(item, "title", "label")
+            tone_raw = item.f.get("tone")
+            if not text and isinstance(tone_raw, str) and token(tone_raw) not in TONE_NAMES:
+                # {"status": "Shipped"}: the status word is the badge text.
+                text = clean_text(tone_raw)
+            if not text:
+                continue
+            badges.append(self.badge_element(self.with_icon(text, item), tone_of(tone_raw, text), item.path))
+        if not badges:
+            return []
+        return [badges[0]] if len(badges) == 1 else [theme.badge_row(badges)]
+
+    def r_progress(self, node: Node, depth: int) -> list[dict]:
+        label = clean_text(node.f.get("label")) or clean_text(node.f.get("title")) or "Progress"
+        maximum = as_number(node.f.get("max"))
+        parsed = parse_number(node.f.get("value"))
+        if maximum is not None and maximum <= 0:
+            self.ctx.warn(node.path + ".max", "invalid_value", "max must be positive; 100 was used.")
+            maximum = None
+        value = None
+        if parsed is not None:
+            value = parsed.value
+            if parsed.denominator and maximum is None:
+                maximum = parsed.denominator
+            elif parsed.percent:
+                value = value / 100 * (maximum or 100)
+            elif maximum is None and 0 < value < 1 and not float(value).is_integer():
+                value *= 100
+                self.ctx.fixed(node.path + ".value", "fraction_as_percent")
+        elif node.f.get("value") not in (None, ""):
+            self.ctx.warn(node.path + ".value", "invalid_value", "Progress value was not a number; shown as in progress.")
+        maximum = maximum or 100
+        if value is None:
+            items = theme.progress(label, "In progress", None)
+            return [self.extension({"type": "ProgressBar", "max": maximum}, items[0], node.path)] if self.native_ok("ProgressBar") else items
+        fraction = max(0.0, value / maximum)
+        value_text = f"{format_number(round(value, 2))}%" if maximum == 100 else f"{format_number(value)} / {format_number(maximum)} ({fraction:.0%})"
+        color = "Good" if fraction >= 1 else "Accent"
+        items = theme.progress(label, value_text, min(1.0, fraction), color)
+        self.need(420, 50, "Progress displays need room for a label and indicator.")
+        if self.native_ok("ProgressBar"):
+            return [items[0], self.extension({"type": "ProgressBar", "value": min(max(value, 0), maximum), "max": maximum}, items[1], node.path)]
+        return items
+
+    def r_spinner(self, node: Node, depth: int) -> list[dict]:
+        label = clean_text(node.f.get("label")) or "Loading"
+        return [self.extension({"type": "ProgressRing", "label": label}, theme.note(label + "…"), node.path)]
+
+    def r_rating(self, node: Node, depth: int) -> list[dict]:
+        parsed = parse_number(node.f.get("value"))
+        if parsed is None:
+            self.ctx.warn(node.path + ".value", "invalid_value", "Rating value was not a number; rating left out.")
+            return []
+        value = parsed.value
+        maximum = as_number(node.f.get("max")) or parsed.denominator or (100 if parsed.percent else 5)
+        maximum = int(maximum) if float(maximum).is_integer() else math.ceil(maximum)
+        if value < 0 or value > maximum or maximum <= 0:
+            self.ctx.warn(node.path + ".value", "invalid_value", f"Rating {format_number(value)} is outside 0–{maximum}; shown as text.")
+            return self.title_prefix(node) + [theme.body(f"Rating: {display_text(node.f.get('value'))}")]
+        count = as_number(node.f.get("count"))
+        caption = f"{format_number(value)} / {maximum}"
+        if count is not None:
+            caption += f" · {format_number(count)} rating{'s' if count != 1 else ''}"
+        if maximum > 10:
+            fallback = theme.body(f"Rating: {caption}")
+            return self.title_prefix(node) + [fallback]
+        fallback = theme.stars(value, maximum, caption)
+        native = {"type": "Rating", "value": value, "max": maximum}
+        if count is not None and float(count).is_integer():
+            native["count"] = int(count)
+        content = self.extension(native, fallback, node.path) if maximum <= 5 else fallback
+        return self.title_prefix(node) + [content]
+
+    # -- media
+
+    def image_size(self, node: Node) -> str:
+        hint = token(node.f.get("size") or node.hints.get("size") or node.hints.get("width") or "")
+        if node.source in {"avatar", "icon"} or hint in {"small", "icon", "thumbnail", "avatar", "xs", "tiny", "sm"}:
+            return "Small"
+        if node.source == "logo" or hint in {"medium", "md", "logo"}:
+            return "Medium"
+        if node.source in {"hero", "banner"} or hint in {"stretch", "full", "fullwidth", "hero", "banner", "cover", "wide", "100", "100%"}:
+            return "Stretch"
+        if hint in {"large", "lg", "big", "xl"}:
+            return "Large"
+        if hint == "auto":
+            return "Auto"
+        return "Stretch" if self.column_depth else "Large"
+
+    def r_image(self, node: Node, depth: int) -> list[dict]:
+        raw = node.f.get("url")
+        link = as_url(raw)
+        caption = clean_text(node.f.get("caption"))
+        if not link:
+            if raw not in (None, ""):
+                self.ctx.warn(node.path + ".url", "invalid_url", "Image URL was not an absolute http(s) link; the image was left out.")
+            else:
+                self.ctx.warn(node.path, "missing_url", "Image had no URL and was left out.")
+            return self.title_prefix(node) + ([theme.note(caption)] if caption else [])
+        if raw != link:
+            self.ctx.fixed(node.path + ".url", "url_normalized")
+        image = {"type": "Image", "url": link, "size": self.image_size(node)}
+        alt = clean_text(node.f.get("alt")) or caption or clean_text(node.f.get("title"))
+        if alt:
+            image["altText"] = alt
+        shape = token(node.f.get("shape") or "")
+        if node.source == "avatar" or shape in {"person", "circle", "round", "rounded", "avatar", "profile", "circular"}:
+            image["style"] = "person"
+        self.need(420, 50, "Images use a fixed template size.")
+        return self.title_prefix(node) + [image] + ([theme.spaced(theme.note(caption), "Small")] if caption else [])
+
+    def r_images(self, node: Node, depth: int) -> list[dict]:
+        raw = node.f.get("images")
+        raw = raw if isinstance(raw, list) else [raw]
+        images = []
+        for i, item in enumerate(raw):
+            link = as_url(item)
+            if not link:
+                self.ctx.warn(f"{node.path}.images[{i}]", "invalid_url", "Image URL was not an absolute http(s) link; it was left out.")
+                continue
+            image = {"type": "Image", "url": link}
+            if isinstance(item, dict):
+                _, alt = pick(item, _keys("alt alt_text caption title description"))
+                if alt:
+                    image["altText"] = clean_text(alt)
+            images.append(image)
+        if not images:
+            return []
+        self.need(min(960, len(images) * 180), 50 if len(images) < 3 else 80, "Image sets wrap to the available width.")
+        return self.title_prefix(node) + [{"type": "ImageSet", "imageSize": "Medium", "images": images}]
+
+    def r_media(self, node: Node, depth: int) -> list[dict]:
+        raw = node.f.get("sources")
+        raw = raw if isinstance(raw, list) else [raw]
+        sources, links = [], []
+        for i, item in enumerate(raw):
+            link = as_url(item)
+            if not link:
+                self.ctx.warn(f"{node.path}.sources[{i}]", "invalid_url", "Media URL was not an absolute http(s) link; it was left out.")
+                continue
+            links.append(link)
+            mime = None
+            if isinstance(item, dict):
+                _, mime = pick(item, _keys("mime_type mimetype mime content_type type"))
+            suffix = "." + link.split("?")[0].split("#")[0].rsplit(".", 1)[-1].lower() if "." in link.rsplit("/", 1)[-1] else ""
+            mime = mime if isinstance(mime, str) and re.fullmatch(r"(?:audio|video)/[a-z0-9.+-]+", mime.strip().lower()) else MIME.get(suffix)
+            if mime:
+                sources.append({"url": link, "mimeType": mime.strip().lower()})
+        if not links:
+            return []
+        title = clean_text(node.f.get("title"))
+        open_button = {"type": "ActionSet", "actions": [{"type": "Action.OpenUrl", "title": f"Open {'media' if not title else title}", "url": links[0]}]}
+        if not sources:
+            self.ctx.fixed(node.path, "media_as_link")
+            return self.title_prefix(node) + [open_button]
+        media = {"type": "Media", "sources": sources, "fallback": open_button}
+        poster = as_url(node.f.get("poster"))
+        if poster:
+            media["poster"] = poster
+        alt = clean_text(node.f.get("alt")) or title
+        if alt:
+            media["altText"] = alt
+        self.need(640, 60, "Media playback needs a larger viewport.")
+        return self.title_prefix(node) + [media]
+
+    # -- charts
+
+    def points(self, raw, labels=None) -> list[tuple[object, object]] | None:
+        """(label, raw value) pairs from a mapping, pair list, {label,value} list or value list."""
+        if isinstance(raw, dict):
+            return list(raw.items())
+        if not isinstance(raw, list):
+            return None
+        if all(not isinstance(v, (dict, list)) for v in raw):
+            if labels is not None and len(labels) == len(raw):
+                return list(zip(labels, raw))
+            if labels is None and all(as_number(v) is not None for v in raw):
+                return [(i + 1, v) for i, v in enumerate(raw)]
+            return None
+        out = []
+        for item in raw:
+            if isinstance(item, list) and len(item) == 2:
+                out.append((item[0], item[1]))
+            elif isinstance(item, dict):
+                if len(item) == 1:
+                    out.append(next(iter(item.items())))
+                    continue
+                lk, label = pick(item, POINT_LABEL_KEYS)
+                rest = {k: v for k, v in item.items() if k != lk}
+                _, value = pick(rest, _keys("value y count amount total number size score"))
+                if value is None and len(rest) == 1:
+                    value = next(iter(rest.values()))
+                if label is None or value is None:
+                    return None
+                out.append((label, value))
+            else:
+                return None
+        return out
+
+    def chart_data(self, node: Node):
+        """Returns (categories, [(series name, [raw values])]) or None."""
+        f = node.f
+        labels = f.get("labels")
+        labels = labels if isinstance(labels, list) else None
+        raw_series = f.get("series")
+        data = f.get("data")
+        if isinstance(data, dict) and any(token(k) == "datasets" for k in data):
+            labels = next((v for k, v in data.items() if token(k) == "labels"), labels)
+            raw_series, data = next(v for k, v in data.items() if token(k) == "datasets"), None
+        if raw_series is None and isinstance(data, dict) and data and all(isinstance(v, (dict, list)) for v in data.values()) \
+                and not all(isinstance(v, list) and len(v) == 2 for v in data.values()):
+            raw_series, data = [{"name": k, "values": v} for k, v in data.items()], None
+        if raw_series is None and isinstance(data, list) and data and all(isinstance(d, dict) for d in data):
+            if all(any(token(k) in SERIES_VALUE_KEYS for k in d) and isinstance(next(v for k, v in d.items() if token(k) in SERIES_VALUE_KEYS), (list, dict)) for d in data):
+                raw_series, data = data, None
+            elif self.points(data) is None or any(len(d) > 2 for d in data):
+                # Records: one label field and one or more numeric fields.
+                keys = list(dict.fromkeys(k for d in data for k in d))
+                numeric = [k for k in keys if all(as_number(d.get(k)) is not None for d in data)]
+                label_keys = [k for k in keys if k not in numeric]
+                if numeric and len(label_keys) <= 1:
+                    lk = label_keys[0] if label_keys else None
+                    labels = [d.get(lk, i + 1) if lk else i + 1 for i, d in enumerate(data)]
+                    raw_series = [{"name": humanize(k), "values": dict(zip(map(display_text, labels), (d[k] for d in data)))} for k in numeric]
+                    data = None
+                    if not f.get("x_label") and lk:
+                        f["x_label"] = humanize(lk)
+                    self.ctx.fixed(node.path, "records_as_chart_series")
+        if raw_series is not None:
+            if isinstance(raw_series, dict):
+                raw_series = [{"name": k, "values": v} for k, v in raw_series.items()]
+            series = []
+            for i, s in enumerate(raw_series if isinstance(raw_series, list) else []):
+                if not isinstance(s, dict):
+                    continue
+                _, name = pick(s, SERIES_NAME_KEYS)
+                _, values = pick(s, SERIES_VALUE_KEYS)
+                pts = self.points(values, labels)
+                if pts is None:
+                    return None
+                series.append((clean_text(name) or f"Series {i + 1}", pts))
+        else:
+            pts = self.points(data if data is not None else f.get("values"), labels)
+            if pts is None:
+                return None
+            series = [(clean_text(f.get("y_label")) or clean_text(f.get("title")) or "Value", pts)]
+        if not series or not any(pts for _, pts in series):
+            return None
+        categories = list(dict.fromkeys(display_text(x) if not isinstance(x, (int, float)) else x for _, pts in series for x, _ in pts))
+        table = []
+        for name, pts in series:
+            lookup = {}
+            for x, y in pts:
+                lookup.setdefault(display_text(x) if not isinstance(x, (int, float)) else x, y)
+            table.append((name, [lookup.get(c) for c in categories]))
+        return categories, table
+
+    def chart_kind(self, node: Node) -> str | None:
+        t = token(node.f.get("chart_type") or "")
+        hints = node.hints
+        if as_bool(hints.get("stacked"), False):
+            t += "stacked"
+        if as_bool(hints.get("horizontal"), False) or token(hints.get("orientation", "")) == "horizontal":
+            t += "horizontal"
+        for words, kind in ((("gauge", "meter", "dial", "speedo"), "gauge"), (("donut", "doughnut", "ring"), "donut"), (("pie",), "pie"),
+                            (("line", "area", "trend", "time", "spark", "scatter"), "line")):
+            if any(w in t for w in words):
+                return kind
+        if "stack" in t:
+            return "stacked_horizontal_bar" if "horizontal" in t else "stacked_bar"
+        if any(w in t for w in ("group", "cluster", "multi", "sidebyside")):
+            return "grouped_bar"
+        if "horizontal" in t or t in {"hbar", "barh"}:
+            return "horizontal_bar"
+        if any(w in t for w in ("bar", "column", "histogram", "vertical")):
+            return "bar"
+        if t:
+            self.ctx.warn(node.path + ".chart_type", "unknown_chart_type", f"Chart type '{node.f.get('chart_type')}' is not supported; a suitable type was chosen.")
+        return None
+
+    def r_chart(self, node: Node, depth: int) -> list[dict]:
+        kind = self.chart_kind(node)
+        if kind == "gauge" or (kind is None and node.f.get("value") is not None and node.f.get("data") is None and node.f.get("series") is None):
+            return self.gauge(node)
+        parsed = self.chart_data(node)
+        if parsed is None:
+            if node.f.get("value") is not None:
+                return self.gauge(node)
+            self.ctx.warn(node.path, "invalid_chart_data", "Chart data could not be read; use \"data\": {\"Label\": number}.")
+            return self.title_prefix(node)
+        categories, series = parsed
+        numbers = [[parse_number(v) for v in values] for _, values in series]
+        unreadable = any(v is not None and n is None for (_, values), nums in zip(series, numbers) for v, n in zip(values, nums))
+        gaps = any(v is None for _, values in series for v in values)
+        values = [[n.value if n else None for n in nums] for nums in numbers]
+        multi = len(series) > 1
+        if kind is None:
+            dates = all(as_date(c)[0] for c in categories if isinstance(c, str)) and all(isinstance(c, str) for c in categories)
+            kind = "line" if dates and len(categories) >= 3 else ("grouped_bar" if multi else "bar")
+        if multi and kind in {"bar", "horizontal_bar", "pie", "donut"}:
+            if kind in {"pie", "donut"}:
+                self.ctx.warn(node.path, "chart_type_changed", "Pie/donut charts show one series; several series are shown as grouped bars.")
+            kind = "grouped_bar"
+        if not multi and kind in {"grouped_bar", "stacked_bar", "stacked_horizontal_bar"}:
+            kind = "bar"
+        flat = [v for row in values for v in row if v is not None]
+        if kind in {"pie", "donut"} and (any(v < 0 for v in flat) or sum(flat) <= 0):
+            self.ctx.warn(node.path, "chart_type_changed", "Pie/donut values must be positive; shown as a bar chart.")
+            kind = "bar"
+        if "stacked" in kind and any(v < 0 for v in flat):
+            kind = "grouped_bar"
+        x_values = categories
+        if kind == "line":
+            dates = [as_date(c)[0] if isinstance(c, str) else None for c in categories]
+            nums = [as_number(c) for c in categories]
+            if all(dates):
+                x_values = dates
+            elif all(n is not None for n in nums):
+                x_values = nums
+            else:
+                x_values = None
+            if x_values is not None and len(set(x_values)) == len(x_values) and x_values != sorted(x_values):
+                order = sorted(range(len(x_values)), key=lambda i: x_values[i])
+                x_values = [x_values[i] for i in order]
+                categories = [categories[i] for i in order]
+                values = [[row[i] for i in order] for row in values]
+                series = [(name, [vals[i] for i in order]) for name, vals in series]
+                self.ctx.fixed(node.path, "line_points_sorted_by_x")
+            if x_values is None or len(set(x_values)) != len(x_values):
+                if self.native:
+                    self.ctx.fixed(node.path, "line_with_categories_as_bars")
+                kind = "grouped_bar" if multi else "bar"
+                x_values = categories
+        if unreadable:
+            self.ctx.warn(node.path, "chart_values_not_numeric", "Some chart values were not numbers, so the data is shown as a table.")
+        fallback = self.chart_fallback(node, kind, categories, series, values, force_table=unreadable)
+        self.need(640, 60 if not multi else 80, "Charts need room for data and axis labels.")
+        prefix = self.title_prefix(node)
+        if unreadable or gaps or not self.native_ok(NATIVE_CHARTS[kind]):
+            if gaps and self.native_ok(NATIVE_CHARTS[kind]):
+                self.ctx.warn(node.path, "chart_missing_values", "Series have different categories; shown as a table with blanks rather than inventing zeros.")
+            return prefix + fallback
+        native = {"type": NATIVE_CHARTS[kind]}
+        if clean_text(node.f.get("title")):
+            native.update(title=clean_text(node.f["title"]), showTitle=False)
+        for key, prop in (("x_label", "xAxisTitle"), ("y_label", "yAxisTitle")):
+            if clean_text(node.f.get(key)) and kind not in {"pie", "donut"}:
+                native[prop] = clean_text(node.f[key])
+        cats = [display_text(c) for c in categories]
+        if kind in {"pie", "donut"}:
+            native["data"] = [{"legend": c, "value": v} for c, v in zip(cats, values[0])]
+        elif kind in {"bar", "horizontal_bar"}:
+            native["data"] = [{"x": c, "y": v} for c, v in zip(cats, values[0])]
+        elif kind == "stacked_horizontal_bar":
+            native["data"] = [{"title": c, "data": [{"legend": name, "value": vals[i]} for (name, _), vals in zip(series, values)]} for i, c in enumerate(cats)]
+        else:
+            xs = x_values if kind == "line" else cats
+            native["data"] = [{"legend": name, "values": [{"x": x, "y": v} for x, v in zip(xs, vals)]} for (name, _), vals in zip(series, values)]
+            if kind == "stacked_bar":
+                native["stacked"] = True
+        wrapped = fallback[0] if len(fallback) == 1 else {"type": "Container", "items": fallback}
+        return prefix + [self.extension(native, wrapped, node.path)]
+
+    def chart_fallback(self, node, kind, categories, series, values, *, force_table=False) -> list[dict]:
+        labels = [display_text(c) for c in categories]
+        y_label = clean_text(node.f.get("y_label"))
+        if not force_table and len(series) == 1 and kind in {"bar", "horizontal_bar", "pie", "donut", "line"} and all(v is not None and v >= 0 for v in values[0]):
+            top = max(values[0]) or 1
+            total = sum(values[0])
+            label_px = max(56, min(180, max(len(l) for l in labels) * 7 + 8))
+            rows = []
+            for label, raw, v in zip(labels, series[0][1], values[0]):
+                text = display_text(raw) if isinstance(raw, str) else format_number(v)
+                if kind in {"pie", "donut"} and total:
+                    text += f" ({v / total:.0%})"
+                rows.append(theme.bar_row(label, v / top, text, label_px))
+            return ([theme.note(y_label)] if y_label else []) + rows
+        x_label = clean_text(node.f.get("x_label")) or ("Date" if kind == "line" else "Category")
+        headers = [x_label, *[name for name, _ in series]]
+        rows = [[label, *[display_text(vals[i]) if vals[i] is not None else "—" for _, vals in series]] for i, label in enumerate(labels)]
+        table_node = Node("table", {"columns": headers, "rows": rows}, node.path)
+        return ([theme.note(y_label)] if y_label else []) + self.r_table(table_node, 0)
+
+    def gauge(self, node: Node) -> list[dict]:
+        parsed = parse_number(node.f.get("value"))
+        if parsed is None:
+            self.ctx.warn(node.path + ".value", "invalid_value", "Gauge value was not a number; gauge left out.")
+            return self.title_prefix(node)
+        low = as_number(node.f.get("min"))
+        high = as_number(node.f.get("max"))
+        low = 0 if low is None else low
+        high = parsed.denominator or (100 if high is None else high)
+        if high <= low:
+            low, high = min(low, high), max(low, high) if high != low else low + 100
+            self.ctx.warn(node.path, "invalid_range", "Gauge max must exceed min; the range was corrected.")
+        value = parsed.value
+        segments = []
+        raw_segments = node.f.get("segments")
+        pts = self.points(raw_segments) if raw_segments is not None else None
+        if pts:
+            sizes = [(display_text(k), as_number(v)) for k, v in pts]
+            if all(s is not None and s > 0 for _, s in sizes):
+                total = sum(s for _, s in sizes)
+                if math.isclose(total, high - low, rel_tol=1e-9):
+                    segments = sizes
+                elif all(a < b for (_, a), (_, b) in zip(sizes, sizes[1:])) and math.isclose(sizes[-1][1], high):
+                    ends = [s for _, s in sizes]
+                    segments = [(n, e - s) for (n, e), s in zip(sizes, [low, *ends[:-1]])]
+                    self.ctx.fixed(node.path + ".segments", "segment_endpoints_to_sizes")
+            if not segments:
+                self.ctx.warn(node.path + ".segments", "invalid_segments", "Gauge segments did not cover min–max and were left out.")
+        label = clean_text(node.f.get("title")) or clean_text(node.f.get("label")) or "Value"
+        fraction = (value - low) / (high - low)
+        value_text = f"{format_number(value)} / {format_number(high)}" if low == 0 else f"{format_number(value)} (range {format_number(low)}–{format_number(high)})"
+        items = theme.progress(label, value_text, max(0.0, min(1.0, fraction)))
+        if segments:
+            ranges, start = [], low
+            for name, size in segments:
+                ranges.append(f"{name} {format_number(start)}–{format_number(start + size)}")
+                start += size
+            items.append(theme.spaced(theme.note(" · ".join(ranges)), "None"))
+        self.need(420, 50, "Gauges need room for a label and indicator.")
+        native = {"type": "Chart.Gauge", "min": low, "max": high, "value": min(max(value, low), high), "valueFormat": "fraction",
+                  "segments": [{"legend": n, "size": s} for n, s in (segments or [("Range", high - low)])]}
+        if node.f.get("title"):
+            native.update(title=label, showTitle=False)
+        if self.native_ok("Chart.Gauge"):
+            return [self.extension(native, {"type": "Container", "items": items}, node.path)]
+        return items
+
+    # -- layout
+
+    def r_section(self, node: Node, depth: int) -> list[dict]:
+        title = clean_text(node.f.get("title"))
+        children = self.render_list(node.f.get("elements", []), node.path + ".elements", depth + 1)
+        if not children:
+            return [theme.spaced(theme.heading(title), "Large")] if title else []
+        if not title and len(children) == 1:
+            return children
+        items = ([theme.group_title(self.with_icon(title, node))] if title else []) + children
+        return [theme.spaced({"type": "Container", "items": items}, "Large" if depth == 0 else "Medium", separator=depth == 0 and bool(title))]
+
+    def column_record(self, record: dict, path: str) -> dict:
+        """A flat product/plan record -> {title, elements}."""
+        title_key, title = pick(record, _keys("title name label heading product plan tier header"))
+        elements = []
+        for key, value in record.items():
+            t = token(key)
+            if key == title_key or value in (None, "", [], {}):
+                continue
+            if t in _keys("image img photo picture logo thumbnail image_url imageurl") and as_url(value):
+                elements.insert(0, {"type": "image", "url": value, "alt": display_text(title or "")})
+            elif t in _keys("badge tag label ribbon highlight status"):
+                elements.append({"type": "badge", "text": value})
+            elif t in _keys("description summary details detail text body content blurb about overview"):
+                elements.append({"type": "text", "text": value})
+            elif t in _keys("rating stars score") and as_number(value) is not None:
+                elements.append({"type": "rating", "value": value})
+            elif t in _keys("url link href website cta") and as_url(value):
+                elements.append({"type": "buttons", "buttons": [{"label": f"View {display_text(title)}" if title else "View details", "url": value}]})
+            elif isinstance(value, list) and all(isinstance(v, str) for v in value):
+                elements.append({"type": "list", "title": humanize(key), "items": value})
+            elif isinstance(value, dict):
+                elements.append({"type": "facts", "title": humanize(key), "facts": value})
+            else:
+                if elements and elements[-1].get("type") == "facts" and elements[-1].get("_auto"):
+                    elements[-1]["facts"][humanize(key)] = value
+                else:
+                    elements.append({"type": "facts", "facts": {humanize(key): value}, "_auto": True})
+        for e in elements:
+            e.pop("_auto", None)
+        self.ctx.fixed(path, "record_as_column")
+        return {"title": title, "elements": elements}
+
+    def r_columns(self, node: Node, depth: int) -> list[dict]:
+        raw_columns = node.f.get("columns")
+        if isinstance(raw_columns, dict):
+            raw_columns = [{"title": k, "elements": v if isinstance(v, list) else [v]} for k, v in raw_columns.items()]
+        if not isinstance(raw_columns, list) or not raw_columns:
+            self.ctx.warn(node.path, "empty_element", "Columns had no content and were left out.")
+            return []
+        specs = []
+        for i, raw in enumerate(raw_columns):
+            p = f"{node.path}.columns[{i}]"
+            if isinstance(raw, list):
+                specs.append((None, raw))
+            elif isinstance(raw, dict):
+                keys = {token(k): k for k in raw}
+                element_key = next((keys[t] for t in _keys("elements items body children content components blocks widgets") if t in keys
+                                    and isinstance(raw[keys[t]], list)), None)
+                if element_key:
+                    _, title = pick({k: v for k, v in raw.items() if k != element_key}, _keys("title heading header label name"))
+                    specs.append((title, raw[element_key]))
+                elif any(t in TYPE_KEYS for t in keys) and token(raw[next(keys[t] for t in keys if t in TYPE_KEYS)]) not in {"column", "col"}:
+                    specs.append((None, [raw]))
+                else:
+                    record = self.column_record({k: v for k, v in raw.items() if token(k) not in TYPE_KEYS}, p)
+                    specs.append((record["title"], record["elements"]))
+            elif raw not in (None, ""):
+                specs.append((None, [raw]))
+        if len(specs) == 1:
+            title, elements = specs[0]
+            return self.r_section(Node("section", {"title": title, "elements": elements}, node.path), depth)
+        outer = (self.min_width, self.floor_percent, self.force_overflow)
+        rendered, widths = [], []
+        self.column_depth += 1
+        for i, (title, elements) in enumerate(specs):
+            self.min_width, self.floor_percent, self.force_overflow = 160, 0, False
+            items = [theme.group_title(clean_text(title))] if clean_text(title) else []
+            items += self.render_list(elements, f"{node.path}.columns[{i}].elements", depth + 1)
+            if not items:
+                continue
+            widths.append(self.column_minimum(items))
+            only_inputs = all(_is_input(item) for item in items if item.get("type") != "TextBlock")
+            rendered.append(theme.column(items, **({} if only_inputs else {"style": "emphasis"})))
+        self.column_depth -= 1
+        self.min_width, self.floor_percent, self.force_overflow = outer
+        if not rendered:
+            return []
+        count = len(rendered)
+        minimum = max(widths) * count + 16 * (count - 1) + 32
+        floor = 50 if count == 1 else 60 if count == 2 else 80 if count <= 4 else 100
+        self.need(minimum, floor, f"{count} side-by-side columns preserve all their content.", overflow=count > 6)
+        return [theme.spaced(theme.row(*rendered), "Medium")]
+
+    def column_minimum(self, items: list[dict]) -> int:
+        minimum = 160
+        for item in items:
+            kind = item.get("type", "")
+            if kind.startswith("Input."):
+                minimum = max(minimum, 240)
+            elif kind == "Media" or kind.startswith("Chart."):
+                minimum = max(minimum, 420)
+            elif kind == "Table":
+                minimum = max(minimum, 96 * len(item["columns"]) + 16)
+            elif kind == "Container":
+                minimum = max(minimum, self.column_minimum(item["items"]))
+            elif kind == "ColumnSet":
+                widths = [self.column_minimum(c["items"]) for c in item["columns"]]
+                minimum = max(minimum, sum(widths) + 8 * (len(widths) - 1) if len(widths) > 2 else max(widths) * len(widths))
+            elif kind == "ActionSet":
+                minimum = max(minimum, max((min(320, len(a["title"]) * 7 + 32) for a in item["actions"]), default=160))
+        return minimum
+
+    # -- buttons
+
+    def button(self, raw, path: str, primary_available: bool) -> dict | None:
+        if isinstance(raw, str):
+            raw = {"label": raw}
+        if not isinstance(raw, dict):
+            return None
+        b = {}
+        for k, v in raw.items():
+            name = BUTTON_MAP.get(token(k))
+            if name and name not in b and v is not None:
+                b[name] = v
+        label = clean_text(b.get("label"))
+        action = token(b.get("action") or "")
+        link_raw = b.get("url")
+        if action and action not in SUBMIT_WORDS and action not in LINK_WORDS and as_url(b.get("action")):
+            link_raw = link_raw or b.get("action")
+            action = "openurl"
+        wants_link = action in LINK_WORDS or (link_raw is not None and action not in SUBMIT_WORDS)
+        if action in _keys("showcard actionshowcard togglevisibility actiontogglevisibility"):
+            self.ctx.warn(path, "unsupported_action", "Show-card and toggle actions are not supported; shown as a regular button.")
+        icon = b.get("icon")
+        if isinstance(icon, str) and 0 < len(icon.strip()) <= 4 and not icon.isascii() and label:
+            label = f"{icon.strip()} {label}"
+        style_word = token(b.get("style") or "")
+        explicit = ("positive" if style_word in _keys("primary positive success green confirm cta main") else
+                    "destructive" if style_word in _keys("danger destructive red negative delete critical warning") else
+                    "default" if style_word else None)
+        if wants_link:
+            link = as_url(link_raw)
+            if not link:
+                self.ctx.warn(path, "invalid_url", f"Button '{label or 'link'}' had no valid http(s) URL and was left out.")
+                return None
+            result = {"type": "Action.OpenUrl", "title": label or "Open link", "url": link}
+        else:
+            label = label or "Submit"
+            data = b.get("data")
+            if data is None and action and action not in SUBMIT_WORDS:
+                data = b.get("action")
+            if isinstance(data, str) and data.strip()[:1] == "{":
+                try:
+                    data = json.loads(data)
+                except ValueError:
+                    pass
+            if data is None:
+                data = {"action": slug(label, "action")}
+                self.ctx.fixed(path, "generated_submit_data")
+            elif not isinstance(data, dict):
+                data = {"action": submit_text(data)}
+            result = {"type": "Action.Submit", "title": label, "data": data}
+        style = theme.button_style(result["title"], explicit, primary_available)
+        if style:
+            result["style"] = style
+        return result
+
+    def buttons(self, raw_list, path: str) -> list[dict]:
+        raw_list = raw_list if isinstance(raw_list, list) else [raw_list]
+        out, primary = [], True
+        for i, raw in enumerate(raw_list):
+            action = self.button(raw, f"{path}[{i}]", primary)
+            if action:
+                primary = primary and action.get("style") != "positive"
+                out.append(action)
+        return out
+
+    def r_buttons(self, node: Node, depth: int) -> list[dict]:
+        actions = []
+        for item in [node, *node.f.get("_merged", [])]:
+            raw = item.f.get("buttons")
+            if raw is None:
+                single = {k: v for k, v in item.f.items() if k in {"label", "url", "data", "action", "style"}}
+                raw = [single] if single else []
+            actions += self.buttons(raw, item.path + ".buttons")
+        if not actions:
+            return []
+        return [theme.spaced({"type": "ActionSet", "actions": actions[i:i + 5]}, "Medium") for i in range(0, len(actions), 5)]
+
+    # -- inputs
+
+    def generated_id(self, base: str) -> str:
+        result, n = base, 2
+        while result in self.used_ids or result in self.reserved_ids:
+            result, n = f"{base}_{n}", n + 1
+        return result
+
+    def input_base(self, node: Node, default_label: str) -> dict:
+        f = node.f
+        label = clean_text(f.get("label"))
+        explicit = f.get("id")
+        ident = as_id(explicit) if explicit is not None else None
+        if explicit is not None and ident is None:
+            self.ctx.warn(node.path + ".id", "invalid_id", "The id could not be used; an id was generated from the label.")
+        if ident and ident != explicit:
+            self.ctx.fixed(node.path + ".id", "id_sanitized", source=display_text(explicit), target=ident)
+        if ident and ident in self.used_ids:
+            new = self.generated_id(ident)
+            self.ctx.warn(node.path + ".id", "duplicate_id", f"Input id '{ident}' was already used; this input submits as '{new}'.")
+            ident = new
+        if not ident:
+            ident = self.generated_id(slug(label or default_label))
+        self.used_ids.add(ident)
+        self.input_ids.append(ident)
+        if not label:
+            label = humanize(display_text(explicit)) if explicit is not None and is_slug_like(explicit) else default_label
+        required = as_bool(f.get("required"), None)
+        if required is None and "optional" in node.hints:
+            required = not as_bool(node.hints["optional"], False)
+        if f.get("required") is not None and as_bool(f.get("required"), None) is None:
+            self.ctx.fixed(node.path + ".required", "unreadable_boolean_default_false")
+        out = {"id": ident, "label": label}
+        if required:
+            out["isRequired"] = True
+            out["errorMessage"] = clean_text(f.get("error_message")) or f"Please complete {label}."
+        elif clean_text(f.get("error_message")):
+            out["errorMessage"] = clean_text(f["error_message"])
+        self.need(480, 50, "Form inputs need readable labels and entry space.")
+        return out
+
+    def input_spacing(self, element: dict) -> dict:
+        return theme.spaced(element, "Medium")
+
+    def r_text_input(self, node: Node, depth: int) -> list[dict]:
+        f = node.f
+        out = self.input_base(node, "Your answer")
+        out = {"type": "Input.Text", **out}
+        hint = token(f.get("format") or "")
+        fmt = next((name for name, words in (("email", ("email", "mail")), ("tel", ("tel", "phone", "mobile")),
+                                              ("url", ("url", "link", "website", "uri")), ("password", ("password", "secret")))
+                    if any(w in hint for w in words)), None)
+        if fmt is None and not hint:
+            probe = token(out["label"] + " " + out["id"])
+            fmt = next((name for name, words in (("email", ("email",)), ("tel", ("phone", "mobile", "telephone")),
+                                                  ("url", ("website", "url")), ("password", ("password",))) if any(w in probe for w in words)), None)
+            if fmt:
+                self.ctx.fixed(node.path, "format_inferred_from_label", target=fmt)
+        if fmt:
+            out["style"] = fmt
+        placeholder = clean_text(f.get("placeholder"))
+        if placeholder:
+            out["placeholder"] = placeholder
+        multiline = as_bool(f.get("multiline"), None)
+        if multiline is None and isinstance(f.get("multiline"), (int, float)):
+            multiline = f["multiline"] > 1
+        if multiline is None and not fmt:
+            multiline = any(w in out["label"].casefold() for w in ("comment", "feedback", "description", "notes", "message", "explain", "reason", "justification", "details"))
+        if multiline:
+            out["isMultiline"] = True
+            self.need(560, 60, "Multiline text entry benefits from more horizontal space.")
+        if f.get("value") is not None:
+            out["value"] = display_text(f["value"])
+        if f.get("max_length") is not None:
+            limit = as_number(f["max_length"])
+            if limit is None or limit < 1:
+                self.ctx.warn(node.path + ".max_length", "invalid_value", "max_length was not a positive number and was left out.")
+            elif len(out.get("value", "").encode("utf-16-le")) // 2 > limit:
+                self.ctx.warn(node.path + ".max_length", "invalid_value", "The initial text is longer than max_length, so the limit was left out.")
+            else:
+                out["maxLength"] = int(limit)
+        if isinstance(f.get("regex"), str) and f["regex"]:
+            out["regex"] = f["regex"]
+        if f.get("_unsupported"):
+            self.ctx.warn(node.path, "unsupported_input", f"{f['_unsupported'].capitalize()} is not available in Adaptive Cards; a URL text box is shown instead.")
+        return [self.input_spacing(out)]
+
+    def r_number_input(self, node: Node, depth: int) -> list[dict]:
+        f = node.f
+        out = {"type": "Input.Number", **self.input_base(node, "Number")}
+        unit = clean_text(f.get("unit"))
+        if unit and unit.casefold() not in out["label"].casefold():
+            out["label"] = f"{out['label']} ({unit})"
+        bounds = {k: as_number(f.get(k)) for k in ("min", "max") if f.get(k) is not None}
+        for k in ("min", "max"):
+            if f.get(k) is not None and bounds.get(k) is None:
+                self.ctx.warn(f"{node.path}.{k}", "invalid_value", f"{k} was not a number and was left out.")
+                bounds.pop(k, None)
+        if "min" in bounds and "max" in bounds and bounds["min"] > bounds["max"]:
+            bounds["min"], bounds["max"] = bounds["max"], bounds["min"]
+            self.ctx.fixed(node.path, "swapped_min_max")
+        out.update(bounds)
+        if f.get("value") is not None:
+            value = as_number(f["value"])
+            if value is None or ("min" in bounds and value < bounds["min"]) or ("max" in bounds and value > bounds["max"]):
+                self.ctx.warn(node.path + ".value", "invalid_value", "Initial value was not a number within min–max and was left out.")
+            else:
+                out["value"] = value
+        if clean_text(f.get("placeholder")):
+            out["placeholder"] = clean_text(f["placeholder"])
+        return [self.input_spacing(out)]
+
+    def temporal(self, node: Node, kind: str) -> dict:
+        f = node.f
+        out = {"type": "Input.Date" if kind == "date" else "Input.Time", **self.input_base(node, "Date" if kind == "date" else "Time")}
+        parse = (lambda v: as_date(v, self.config.day_first)) if kind == "date" else (lambda v: (as_time(v), False))
+        for key in ("min", "max", "value"):
+            raw = f.get(key)
+            if raw is None or raw == "":
+                continue
+            value, ambiguous = parse(raw)
+            if value is None:
+                self.ctx.warn(f"{node.path}.{key}", "invalid_value", f"{key} '{display_text(raw)}' is not a {kind} that can be read exactly; it was left out.")
+                continue
+            if ambiguous:
+                self.ctx.warn(f"{node.path}.{key}", "ambiguous_date", f"'{raw}' read as {value} ({'day' if self.config.day_first else 'month'} first).")
+            elif value != raw:
+                self.ctx.fixed(f"{node.path}.{key}", f"{kind}_normalized", source=display_text(raw), target=value)
+            out[key] = value
+        if "min" in out and "max" in out and out["min"] > out["max"]:
+            out["min"], out["max"] = out["max"], out["min"]
+            self.ctx.fixed(node.path, "swapped_min_max")
+        if "value" in out and (("min" in out and out["value"] < out["min"]) or ("max" in out and out["value"] > out["max"])):
+            self.ctx.warn(node.path + ".value", "invalid_value", "Initial value was outside min–max and was left out.")
+            del out["value"]
+        return out
+
+    def r_date_input(self, node: Node, depth: int) -> list[dict]:
+        return [self.input_spacing(self.temporal(node, "date"))]
+
+    def r_time_input(self, node: Node, depth: int) -> list[dict]:
+        return [self.input_spacing(self.temporal(node, "time"))]
+
+    def r_datetime_input(self, node: Node, depth: int) -> list[dict]:
+        f = dict(node.f)
+        date_part = time_part = None
+        raw = f.pop("value", None)
+        if isinstance(raw, str):
+            m = re.match(r"(.*?)[T\s,]+(\d{1,2}(?::\d{2})?(?::\d{2})?\s*(?:[ap]\.?m\.?)?)\s*(?:Z|[+-]\d{2}:?\d{2})?$", raw.strip(), re.I)
+            date_part, time_part = (m.group(1), m.group(2)) if m else (raw, None)
+        label = clean_text(f.get("label")) or "Date"
+        base_id = as_id(f.get("id")) or slug(label)
+        date_node = Node("date_input", {**f, "id": base_id + "_date", "label": label, "value": date_part,
+                                        "min": f.get("min"), "max": f.get("max")}, node.path)
+        time_node = Node("time_input", {"id": base_id + "_time", "label": "Time", "value": time_part,
+                                        "required": f.get("required")}, node.path)
+        date_input, time_input = self.temporal(date_node, "date"), self.temporal(time_node, "time")
+        self.ctx.fixed(node.path, "datetime_split", ids=[date_input["id"], time_input["id"]])
+        return [self.input_spacing(theme.row(theme.column([date_input]), theme.column([time_input])))]
+
+    def choice_options(self, raw, node: Node) -> list[tuple[str, str | None]]:
+        """(title, explicit value or None)."""
+        if isinstance(raw, str):
+            parts = raw.splitlines() if "\n" in raw else re.split(r"\s*[;|]\s*", raw) if re.search(r"[;|]", raw) else re.split(r"\s*,\s*", raw)
+            raw = [p for p in parts if p.strip()]
+            self.ctx.fixed(node.path + ".options", "options_split_from_text")
+        if isinstance(raw, dict):
+            items = list(raw.items())
+            keys_slug = all(re.fullmatch(r"[a-z0-9_\-]+", str(k)) for k, _ in items)
+            values_display = any(isinstance(v, str) and (" " in v or v[:1].isupper()) for _, v in items)
+            if keys_slug and values_display:
+                self.ctx.fixed(node.path + ".options", "options_value_title_order")
+                return [(display_text(v), display_text(k)) for k, v in items]
+            return [(display_text(k), submit_text(v) if not isinstance(v, dict) else None) for k, v in items]
+        options = []
+        for item in raw if isinstance(raw, list) else [raw]:
+            if isinstance(item, dict):
+                if len(item) == 1 and token(next(iter(item))) not in LABEL_KEYS | VALUE_KEYS:
+                    (k, v), = item.items()
+                    options.append((display_text(k), submit_text(v)))
+                    continue
+                tk, title = pick(item, _keys("title label text name display display_name displayname caption option choice"))
+                _, value = pick({k: v for k, v in item.items() if k != tk}, _keys("value id key code val data"))
+                if title is None and value is None:
+                    continue
+                options.append((display_text(title if title is not None else value), submit_text(value) if value is not None else None))
+            elif isinstance(item, list) and len(item) == 2:
+                options.append((display_text(item[0]), submit_text(item[1])))
+            elif item is not None and clean_text(item):
+                options.append((clean_text(item), None))
+        return options
+
+    def r_choice(self, node: Node, depth: int) -> list[dict]:
+        f = node.f
+        options = self.choice_options(f.get("options", []), node)
+        if not options:
+            label = clean_text(f.get("label"))
+            if re.match(r"(do|does|did|is|are|was|were|will|would|can|could|should|have|has|may)\b.*\?\s*$", label, re.I):
+                options = [("Yes", None), ("No", None)]
+                self.ctx.fixed(node.path, "yes_no_options_inferred")
+            else:
+                self.ctx.warn(node.path + ".options", "missing_options", "Choice had no options; a text box is shown instead.")
+                return self.r_text_input(Node("text_input", {k: v for k, v in f.items() if k in SPECS["text_input"].fields}, node.path, node.hints), depth)
+        multiple = as_bool(f.get("multiple"), False)
+        out = {"type": "Input.ChoiceSet", **self.input_base(node, "Choose an option")}
+        seen_titles, choices = set(), []
+        for title, value in options:
+            if title in seen_titles and value is None:
+                self.ctx.fixed(node.path + ".options", "duplicate_option_removed", option=title)
+                continue
+            seen_titles.add(title)
+            choices.append([title, value])
+        used = set()
+        for pair in choices:
+            title, value = pair
+            if value is None or value.strip() == "":
+                value = title.strip()
+                if multiple and "," in value:
+                    value = re.sub(r"\s*,\s*", " ", value)
+            elif multiple and "," in value:
+                value = value.replace(",", "_")
+                self.ctx.warn(node.path + ".options", "value_changed", f"Option value '{pair[1]}' contained a comma, which breaks multi-select; submitted as '{value}'.")
+            base, n = value or "option", 2
+            while value in used or not value:
+                value, n = f"{base}_{n}", n + 1
+            used.add(value)
+            pair[1] = value
+        out["choices"] = [{"title": t, "value": v} for t, v in choices]
+        self.choice_values[out["id"]] = out["choices"]
+        display = token(f.get("display") or "")
+        if display in {"radio", "expanded", "buttons", "list", "checkbox", "checkboxes", "check", "radiobuttons", "radiogroup", "segmented"}:
+            expanded = True
+        elif display in {"dropdown", "compact", "select", "menu", "combo", "combobox", "filtered", "picker"}:
+            expanded = multiple and len(choices) <= 12
+        else:
+            expanded = (multiple and len(choices) <= 12) or (len(choices) <= 4 and max(len(t) for t, _ in choices) <= 60)
+        out.update(isMultiSelect=multiple, style="expanded" if expanded else "compact", wrap=True)
+        placeholder = clean_text(f.get("placeholder"))
+        if placeholder and not expanded:
+            out["placeholder"] = placeholder
+        if f.get("value") not in (None, "", []):
+            selected = self.match_choices(f["value"], choices, multiple, node.path)
+            if selected:
+                out["value"] = ",".join(selected) if multiple else selected[0]
+        return [self.input_spacing(out)]
+
+    def match_choices(self, raw, choices, multiple: bool, path: str) -> list[str]:
+        def find(wanted) -> str | None:
+            text = display_text(wanted).strip()
+            for test in (lambda t, v: v == text, lambda t, v: t == text,
+                         lambda t, v: v.casefold() == text.casefold() or t.casefold() == text.casefold(),
+                         lambda t, v: token(v) == token(text) or token(t) == token(text)):
+                hits = [v for t, v in choices if test(t, v)]
+                if len(hits) == 1:
+                    return hits[0]
+            hits = [v for t, v in choices if token(text) and (token(t).startswith(token(text)) or token(text) in token(t))]
+            return hits[0] if len(hits) == 1 else None
+
+        if isinstance(raw, list):
+            wanted = raw
+        elif multiple and isinstance(raw, str) and find(raw) is None:
+            wanted = [p for p in re.split(r"\s*[,;|]\s*", raw) if p]
+        else:
+            wanted = [raw]
+        found = []
+        for w in wanted:
+            value = find(w)
+            if value is None:
+                self.ctx.warn(path + ".value", "unmatched_default", f"Default '{display_text(w)}' does not match any option and was left out.")
+            elif value not in found:
+                found.append(value)
+                if value != display_text(w):
+                    self.ctx.fixed(path + ".value", "default_matched_to_option", source=display_text(w), target=value)
+        return found if multiple else found[:1]
+
+    def r_checkbox(self, node: Node, depth: int) -> list[dict]:
+        f = node.f
+        base = self.input_base(node, "Yes")
+        on = submit_text(f["on_value"]) if f.get("on_value") not in (None, "") else "true"
+        off = submit_text(f["off_value"]) if f.get("off_value") not in (None, "") else "false"
+        if on == off:
+            self.ctx.warn(node.path, "invalid_value", "on_value and off_value were equal; true/false are submitted instead.")
+            on, off = "true", "false"
+        out = {"type": "Input.Toggle", "id": base["id"], "title": base["label"], "valueOn": on, "valueOff": off, "wrap": True}
+        for key in ("isRequired", "errorMessage"):
+            if key in base:
+                out[key] = base[key]
+        if f.get("value") is not None:
+            raw = f["value"]
+            checked = raw == on if isinstance(raw, str) and raw in (on, off) else as_bool(raw, None)
+            if checked is None:
+                self.ctx.warn(node.path + ".value", "invalid_value", "Checkbox default was not true/false and was left out.")
+            else:
+                out["value"] = on if checked else off
+        return [self.input_spacing(out)]
+
+    def r_rating_input(self, node: Node, depth: int) -> list[dict]:
+        f = node.f
+        out = self.input_base(node, "Rating")
+        maximum = as_number(f.get("max")) or 5
+        maximum = int(max(1, min(10, round(maximum))))
+        half = as_bool(f.get("half_steps"), False)
+        step = 0.5 if half else 1
+        value = as_number(f.get("value")) if f.get("value") is not None else None
+        if value is not None:
+            snapped = round(value / step) * step
+            if not 0 < snapped <= maximum:
+                self.ctx.warn(node.path + ".value", "invalid_value", "Initial rating was outside the allowed range and was left out.")
+                value = None
+            elif snapped != value:
+                self.ctx.fixed(node.path + ".value", "rating_snapped_to_step")
+                value = snapped
+        count = int(maximum / step)
+        titles = [f"{'★' * int(i * step)}{'☆' * (maximum - int(i * step))}  {i * step:g}" if not half else f"{i * step:g} / {maximum}"
+                  for i in range(1, count + 1)]
+        fallback = {"type": "Input.ChoiceSet", **out, "style": "compact",
+                    "choices": [{"title": t, "value": f"{i * step:g}"} for i, t in zip(range(1, count + 1), titles)]}
+        if value is not None:
+            fallback["value"] = f"{value:g}"
+        self.choice_values[out["id"]] = fallback["choices"]
+        if maximum <= 5:
+            native = {"type": "Input.Rating", **out, "max": maximum, "allowHalfSteps": half}
+            if value is not None:
+                native["value"] = value
+            element = self.extension(native, fallback, node.path)
+        else:
+            element = fallback
+        if element is not fallback and "fallback" in element:
+            self.ctx.warn(node.path, "rating_submission_type", "Native rating submits a number; the fallback submits the same rating as a string.")
+        return [self.input_spacing(element)]
+
+    def r_divider(self, node: Node, depth: int) -> list[dict]:
+        return []
+
+    def r_column(self, node: Node, depth: int) -> list[dict]:
+        return self.r_section(node, depth)
+
+    def r_document(self, node: Node, depth: int) -> list[dict]:
+        return self.r_section(node, depth)
+
+    # ------------------------------------------------------------ assembly
+
+    def reserve(self, value, depth=0):
+        """Reserve explicit IDs anywhere in the request so generated IDs never take them."""
+        if depth > self.config.max_depth + 8:
+            return
+        if isinstance(value, dict):
+            for k, v in value.items():
+                if token(k) in {"id", "inputid", "fieldid"} and isinstance(v, str) and as_id(v):
+                    self.reserved_ids.add(as_id(v))
+                self.reserve(v, depth + 1)
+        elif isinstance(value, list):
+            for v in value:
+                self.reserve(v, depth + 1)
+
+    def header(self, doc: dict) -> list[dict]:
+        title = clean_text(doc.get("title"))
+        subtitle = clean_text(doc.get("subtitle"))
+        status = doc.get("status")
+        badge = None
+        if status not in (None, ""):
+            if isinstance(status, dict):
+                node = self.canonicalize({"type": "badge", **status}, "$.status")
+                badge = self.r_badge(node[0], 0) if node else None
+                badge = badge[0] if badge else None
+            elif clean_text(status):
+                badge = self.badge_element(clean_text(status), tone_of(status), "$.status")
+        blocks = ([theme.card_title(title)] if title else []) + ([theme.subtitle(subtitle)] if subtitle else [])
+        if badge and blocks:
+            return [theme.row(theme.column(blocks), theme.column([badge], "auto", verticalContentAlignment="Top"))]
+        return blocks + ([badge] if badge else [])
+
+    def has_submit(self, node) -> bool:
+        if isinstance(node, dict):
+            return node.get("type") == "Action.Submit" or any(self.has_submit(v) for k, v in node.items() if k not in {"data", "fallback"})
+        return isinstance(node, list) and any(self.has_submit(v) for v in node)
+
+    def clean_submit_data(self, node, path="$card"):
+        if isinstance(node, dict):
+            if node.get("type") == "Action.Submit" and isinstance(node.get("data"), dict):
+                clash = set(node["data"]) & self.used_ids
+                if clash:
+                    node["data"] = {k: v for k, v in node["data"].items() if k not in clash}
+                    self.ctx.warn(path, "submit_data_collision", f"Button data keys {sorted(clash)} match input ids and were removed so they cannot overwrite user answers.")
+            for k, v in node.items():
+                if k != "data":
+                    self.clean_submit_data(v, f"{path}.{k}")
+        elif isinstance(node, list):
+            for i, v in enumerate(node):
+                self.clean_submit_data(v, f"{path}[{i}]")
+
+    def width(self) -> dict:
+        target = self.config.available_width_px
+        raw = max(self.floor_percent, math.ceil(self.min_width / target * 100))
+        overflow = self.force_overflow or raw > 100
+        percent = max(110, math.ceil(raw / 10) * 10) if overflow else next(n for n in (50, 60, 80, 100) if n >= raw)
+        return {"suggestedWidth": "100%+" if overflow else f"{percent}%", "widthPercent": percent,
+                "estimatedMinWidthPx": self.min_width, "referenceWidthPx": target,
+                "overflow": "scroll" if overflow else "none", "isEstimate": True, "reasons": self.width_reasons}
+
+    def build(self, request) -> dict:
+        raw = load_request(request, self.ctx)
+        doc = self.document(raw)
+        self.reserve(doc["elements"])
+        body = self.header(doc)
+        content = self.render_list(doc["elements"], "$.elements", 0)
+        if body and content:
+            content[0] = {**content[0], "spacing": "Medium"}
+        body += content
+        explicit_buttons = "buttons" in doc
+        actions = self.buttons(doc.get("buttons") or [], "$.buttons")
+        submit_label = clean_text(doc.get("submit_label"))
+        if submit_label:
+            defaults = [a for a in actions if a["type"] == "Action.Submit" and a["title"] == "Submit"]
+            if len(defaults) == 1:
+                defaults[0]["title"] = submit_label
+            elif not any(a["type"] == "Action.Submit" for a in actions) and not self.has_submit(body):
+                actions.insert(0, {"type": "Action.Submit", "title": submit_label, "style": "positive"})
+            else:
+                self.ctx.fixed("$.submit_label", "submit_label_ignored_buttons_given")
+        elif self.input_ids and not explicit_buttons and not self.has_submit(body) and not any(a["type"] == "Action.Submit" for a in actions):
+            actions.insert(0, {"type": "Action.Submit", "title": "Submit", "style": "positive"})
+        if not body:
+            raise CardError("$.elements", 'Nothing to display. Send elements such as '
+                            '{"title": "Summary", "elements": [{"type": "text", "text": "..."}]}.', "empty_card")
+        card = {"type": "AdaptiveCard", "$schema": "https://adaptivecards.io/schemas/adaptive-card.json", "version": "1.5", "body": body}
+        if len(actions) > 5:
+            body.extend(theme.spaced({"type": "ActionSet", "actions": actions[i:i + 5]}, "Medium") for i in range(0, len(actions), 5))
+        elif actions:
+            card["actions"] = actions
+        self.clean_submit_data(card)
+        if len(json.dumps(card, ensure_ascii=False).encode("utf-8")) > self.config.max_output_bytes:
+            raise CardError("$", "Generated card exceeds the output size limit; split the content into several cards.", "limit_exceeded")
+        layout = self.width()
+        warnings = self.ctx.warnings
+        message = "Card built and ready to display. Do not repeat its contents or call the tool again for the same card."
+        if warnings:
+            notes = "; ".join(f"{w['path']}: {w['message']}" for w in warnings[:3])
+            message = (f"Card built and ready to display, with {len(warnings)} note(s): {notes}"
+                       " The card is usable as is; call again only if important content was left out.")
+        return {"status": "successful", "suggestedWidth": layout.pop("suggestedWidth"), "response": card, "message": message,
+                "metadata": {"profile": self.config.profile, "schemaVersion": "1.5", "inputIds": self.input_ids,
+                             "choiceValues": self.choice_values, "layout": layout, "warnings": warnings,
+                             "normalizations": self.ctx.normalizations}}
+
+
+NATIVE_CHARTS = {"pie": "Chart.Pie", "donut": "Chart.Donut", "bar": "Chart.VerticalBar", "horizontal_bar": "Chart.HorizontalBar",
+                 "grouped_bar": "Chart.VerticalBar.Grouped", "stacked_bar": "Chart.VerticalBar.Grouped",
+                 "stacked_horizontal_bar": "Chart.HorizontalBar.Stacked", "line": "Chart.Line", "gauge": "Chart.Gauge"}
+
+
+def render_card(request, *, config: BuilderConfig | None = None) -> dict:
+    """Accept an element, list, document, or JSON string and return the tool envelope.
+
+    Invalid or unusual input is repaired where it can be done without inventing
+    facts; the repairs are listed in metadata. status="error" is returned only
+    for unreadable requests, empty results and safety limits.
+    """
+    builder = CardBuilder(config or BuilderConfig())
+    try:
+        return builder.build(request)
+    except CardError as exc:
+        detail = exc.detail
+        message = f"{detail['path']}: {detail['message']}"
+        return {"status": "error", "suggestedWidth": None, "response": message, "message": message + " Fix this and call the tool once more.",
+                "errors": [detail], "metadata": {"warnings": builder.ctx.warnings, "normalizations": builder.ctx.normalizations}}