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

adaptive_card_tools/normalize.py

@@ -0,0 +1,581 @@
+"""Lenient parsing of requests and values.
+
+Policy: repair the *form* of what the model sent, never its *facts*. Text is
+never rewritten, numbers are parsed but never estimated, and anything that
+cannot be interpreted safely is dropped with a warning instead of failing the
+whole card. Hard errors are reserved for unreadable requests and safety limits.
+"""
+from __future__ import annotations
+
+import datetime as dt
+import json
+import math
+import re
+import unicodedata
+from dataclasses import dataclass, field
+from decimal import Decimal
+from fractions import Fraction
+from urllib.parse import quote, urlsplit
+
+
+class CardError(ValueError):
+    """Raised only when nothing usable can be built or a safety limit is hit."""
+
+    def __init__(self, path: str, message: str, code: str = "invalid_request", **details):
+        super().__init__(message)
+        self.detail = {"path": path, "code": code, "message": message, **details}
+
+
+@dataclass(frozen=True)
+class BuilderConfig:
+    """Developer settings; never selectable by the model.
+
+    profile: "portable" emits core Adaptive Cards 1.5 only. "microsoft" emits
+        native Microsoft extensions (charts, Badge, Rating, ProgressBar...) with
+        core fallbacks. native_types optionally restricts which extensions a
+        known renderer supports.
+    day_first: how to read ambiguous dates such as 03/04/2026.
+    repair_typos: allow edit-distance matching of type and field names.
+    Widths are estimates relative to available_width_px, not measurements.
+    """
+    profile: str = "portable"
+    native_types: tuple[str, ...] | None = None
+    available_width_px: int = 1200
+    day_first: bool = False
+    repair_typos: bool = True
+    max_elements: int = 150
+    max_items: int = 500
+    max_depth: int = 12
+    max_nodes: int = 20000
+    max_payload_bytes: int = 512000
+    max_output_bytes: int = 2000000
+
+    def __post_init__(self):
+        if self.profile not in {"portable", "microsoft"}:
+            raise ValueError("profile must be 'portable' or 'microsoft'")
+        for name in ("available_width_px", "max_elements", "max_items", "max_depth",
+                     "max_nodes", "max_payload_bytes", "max_output_bytes"):
+            value = getattr(self, name)
+            if type(value) is not int or value < 1:
+                raise ValueError(f"{name} must be a positive integer")
+        for name in ("repair_typos", "day_first"):
+            if type(getattr(self, name)) is not bool:
+                raise ValueError(f"{name} must be boolean")
+        if self.native_types is not None:
+            allowed = {"Input.Rating", "Rating", "Badge", "ProgressBar", "ProgressRing",
+                       "Chart.Pie", "Chart.Donut", "Chart.VerticalBar", "Chart.HorizontalBar",
+                       "Chart.VerticalBar.Grouped", "Chart.HorizontalBar.Stacked", "Chart.Line", "Chart.Gauge"}
+            if not isinstance(self.native_types, tuple) or any(t not in allowed for t in self.native_types):
+                raise ValueError("native_types must be a tuple of supported native extension type names")
+
+
+@dataclass
+class Context:
+    config: BuilderConfig
+    normalizations: list[dict] = field(default_factory=list)
+    warnings: list[dict] = field(default_factory=list)
+
+    def fixed(self, path: str, kind: str, **info):
+        """A repair that kept all content (alias, format conversion, ignored styling)."""
+        entry = {"path": path, "kind": kind, **info}
+        if entry not in self.normalizations:
+            self.normalizations.append(entry)
+
+    def warn(self, path: str, code: str, message: str):
+        """Something was dropped or reinterpreted; the developer or model may care."""
+        entry = {"path": path, "code": code, "message": message}
+        if entry not in self.warnings:
+            self.warnings.append(entry)
+
+
+# ---------------------------------------------------------------- names
+
+def token(value) -> str:
+    """Case-, separator- and Unicode-insensitive form of a name."""
+    return re.sub(r"[\W_]+", "", unicodedata.normalize("NFKC", str(value)).casefold())
+
+
+def edit_distance(a: str, b: str, limit: int = 2) -> int:
+    """Optimal string alignment distance, capped at limit + 1."""
+    if abs(len(a) - len(b)) > limit:
+        return limit + 1
+    prev2, prev = None, list(range(len(b) + 1))
+    for i, ca in enumerate(a, 1):
+        cur = [i] + [0] * len(b)
+        for j, cb in enumerate(b, 1):
+            cur[j] = min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + (ca != cb))
+            if prev2 is not None and i > 1 and j > 1 and ca == b[j - 2] and a[i - 2] == cb:
+                cur[j] = min(cur[j], prev2[j - 2] + 1)
+        if min(cur) > limit:
+            return limit + 1
+        prev2, prev = prev, cur
+    return prev[-1]
+
+
+def closest(name: str, candidates, ctx: Context) -> str | None:
+    """Unique nearest candidate token for a misspelled name, or None."""
+    if not ctx.config.repair_typos or len(name) < 4:
+        return None
+    limit = 1 if len(name) < 8 else 2
+    scored = {}
+    for candidate in candidates:
+        if len(candidate) >= 4:
+            d = edit_distance(name, candidate, limit)
+            if d <= limit:
+                scored.setdefault(d, set()).add(candidate)
+    if not scored:
+        return None
+    best = scored[min(scored)]
+    return next(iter(best)) if len(best) == 1 else None
+
+
+def slug(value, fallback: str = "field") -> str:
+    """Lower snake-case machine name derived from human text."""
+    text = unicodedata.normalize("NFKD", str(value)).encode("ascii", "ignore").decode()
+    result = re.sub(r"[^a-z0-9]+", "_", text.casefold()).strip("_")[:64] or fallback
+    return fallback + "_" + result if result[0].isdigit() else result
+
+
+def is_slug_like(value) -> bool:
+    return isinstance(value, str) and bool(re.fullmatch(r"[A-Za-z_][A-Za-z0-9_.\-]{0,127}", value.strip()))
+
+
+def as_id(value) -> str | None:
+    """Sanitize a caller-supplied input ID, keeping its case and meaning."""
+    if isinstance(value, bool) or not isinstance(value, (str, int)):
+        return None
+    text = re.sub(r"[^A-Za-z0-9_.\-]+", "_", str(value).strip()).strip("_")[:128]
+    if not text:
+        return None
+    return "field_" + text if not re.match(r"[A-Za-z_]", text) else text
+
+
+# ---------------------------------------------------------------- text
+
+def format_number(value) -> str:
+    if isinstance(value, float) and value.is_integer() and abs(value) < 1e15:
+        return str(int(value))
+    return repr(value) if isinstance(value, float) else str(value)
+
+
+def display_text(value) -> str:
+    """Human-facing text for any JSON value."""
+    if value is None:
+        return ""
+    if isinstance(value, bool):
+        return "Yes" if value else "No"
+    if isinstance(value, (int, float)):
+        return format_number(value)
+    if isinstance(value, str):
+        return value
+    if isinstance(value, list):
+        return ", ".join(t for t in (display_text(v) for v in value) if t)
+    if isinstance(value, dict):
+        # A {text|label|title|value} wrapper is usually just a value.
+        for key in ("text", "label", "title", "value", "name", "display"):
+            if key in value and len(value) <= 2:
+                return display_text(value[key])
+        return "; ".join(f"{k}: {display_text(v)}" for k, v in value.items())
+    return str(value)
+
+
+def submit_text(value) -> str:
+    """Machine-facing string for submitted values."""
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, (dict, list)):
+        return json.dumps(value, ensure_ascii=False, sort_keys=True)
+    return display_text(value)
+
+
+def clean_text(value) -> str:
+    """display_text, treating whitespace-only text as empty."""
+    text = display_text(value)
+    return text if text.strip() else ""
+
+
+# ---------------------------------------------------------------- booleans
+
+TRUE_WORDS = {"true", "yes", "y", "1", "on", "checked", "selected", "required", "mandatory",
+              "enabled", "enable", "t", "x", "ok", "multiple", "multi", "many", "always"}
+FALSE_WORDS = {"false", "no", "n", "0", "off", "unchecked", "optional", "disabled", "disable",
+               "f", "none", "null", "", "single", "one", "never", "notrequired"}
+
+
+def as_bool(value, default: bool | None = None) -> bool | None:
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, (int, float)) and math.isfinite(value):
+        return value != 0
+    if isinstance(value, str):
+        word = token(value) if value.strip() not in {"✓", "✔"} else "true"
+        if word in TRUE_WORDS:
+            return True
+        if word in FALSE_WORDS:
+            return False
+    return default
+
+
+# ---------------------------------------------------------------- numbers
+
+_CURRENCY = "$€£¥₹₩₽₺₫₪฿¢"
+_CODES = r"(?:USD|EUR|GBP|CAD|AUD|NZD|JPY|CNY|INR|CHF|SEK|NOK|DKK|MXN|BRL|ZAR|SGD|HKD|US\$|C\$|A\$)"
+_SCALE = {"k": 1e3, "m": 1e6, "mm": 1e6, "mn": 1e6, "b": 1e9, "bn": 1e9}
+_ONE_NUMBER = re.compile(r"[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?")
+
+
+@dataclass(frozen=True)
+class Parsed:
+    value: float | int
+    percent: bool = False
+    denominator: float | int | None = None
+
+
+def _number_core(text: str):
+    if re.fullmatch(r"\d{1,3}(,\d{3})+(\.\d+)?", text):
+        text = text.replace(",", "")
+    elif re.fullmatch(r"\d{1,3}(\.\d{3})+(,\d+)?", text):
+        text = text.replace(".", "").replace(",", ".")
+    elif re.fullmatch(r"\d{1,3}([ '’]\d{3})+(\.\d+)?", text):
+        text = re.sub(r"[ '’]", "", text)
+    elif re.fullmatch(r"\d+,\d+", text):
+        text = text.replace(",", ".")
+    if not re.fullmatch(r"(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?", text) or len(text) > 64:
+        return None
+    return int(text) if re.fullmatch(r"\d+", text) else float(text)
+
+
+def parse_number(value) -> Parsed | None:
+    """Read numbers like 12, "1,200", "$1.2M", "75%", "(40)", "4.5/5", "12 GB"."""
+    if isinstance(value, bool) or value is None:
+        return None
+    if isinstance(value, (int, float)):
+        return Parsed(value) if math.isfinite(value) and abs(value) <= 9007199254740991 else None
+    if isinstance(value, dict):
+        for key in ("value", "amount", "y", "count", "total"):
+            if key in value:
+                return parse_number(value[key])
+        return None
+    if not isinstance(value, str):
+        return None
+    text = unicodedata.normalize("NFKC", value).strip()
+    text = re.sub(r"[−‒–—]", "-", text).replace(" ", " ").replace(" ", " ")
+    fraction = re.fullmatch(r"(.+?)\s*(?:/|out of|of)\s*(.+)", text, re.I)
+    if fraction and not re.search(r"\d+[/-]\d+[/-]\d+", text):
+        top, bottom = parse_number(fraction.group(1)), parse_number(fraction.group(2))
+        if top and bottom and bottom.value > 0 and not top.percent:
+            return Parsed(top.value, denominator=bottom.value)
+    negative = False
+    if re.fullmatch(r"\(.*\)", text):
+        negative, text = True, text[1:-1].strip()
+    text = re.sub(rf"^{_CODES}\s*|\s*{_CODES}$", "", text)
+    sign = ""
+    if text and text[0] in "+-":
+        sign, text = text[0], text[1:].strip()
+    text = text.strip(_CURRENCY + " ~≈")
+    if text and text[0] in "+-" and not sign:
+        sign, text = text[0], text[1:].strip()
+    if not text:
+        return None
+    percent = text.endswith("%")
+    text = text.rstrip("%").strip()
+    scale = 1
+    suffix = re.fullmatch(r"(.*?\d)\s*(k|m|mm|mn|b|bn)", text, re.I)
+    if suffix:
+        text, scale = suffix.group(1), _SCALE[suffix.group(2).lower()]
+    number = _number_core(text)
+    if number is None:
+        # "12 GB", "approx. 40 hours": exactly one number surrounded by words.
+        matches = _ONE_NUMBER.findall(text)
+        leftover = _ONE_NUMBER.sub("", text)
+        if len(matches) != 1 or re.search(r"\d", leftover) or not re.fullmatch(r"[^\W\d]*[\s\w.\-/%]*", leftover):
+            return None
+        number = _number_core(matches[0].lstrip("+"))
+        if number is None:
+            return None
+    if scale != 1:
+        number = number * scale
+        number = int(number) if float(number).is_integer() else number
+    if sign == "-" or negative:
+        number = -number
+    if not math.isfinite(number) or abs(number) > 9007199254740991:
+        return None
+    return Parsed(number, percent=percent)
+
+
+def as_number(value):
+    parsed = parse_number(value)
+    return None if parsed is None else parsed.value
+
+
+# ---------------------------------------------------------------- dates and times
+
+MONTHS = {m: i for i, names in enumerate([("jan", "january"), ("feb", "february"), ("mar", "march"),
+          ("apr", "april"), ("may",), ("jun", "june"), ("jul", "july"), ("aug", "august"),
+          ("sep", "sept", "september"), ("oct", "october"), ("nov", "november"), ("dec", "december")], 1)
+          for m in names}
+
+
+def _valid_date(y: int, m: int, d: int) -> str | None:
+    try:
+        return dt.date(y, m, d).isoformat()
+    except ValueError:
+        return None
+
+
+def as_date(value, day_first: bool = False) -> tuple[str | None, bool]:
+    """Return (YYYY-MM-DD or None, ambiguous). Never invents a missing year."""
+    if isinstance(value, (dt.date, dt.datetime)):
+        return value.isoformat()[:10], False
+    if not isinstance(value, str):
+        return None, False
+    text = value.strip()
+    m = re.match(r"(\d{4})[-/.](\d{1,2})[-/.](\d{1,2})(?:$|[T\s])", text)
+    if m:
+        return _valid_date(*map(int, m.groups())), False
+    m = re.fullmatch(r"(\d{1,2})[-/.](\d{1,2})[-/.](\d{2}|\d{4})", text)
+    if m:
+        a, b, y = map(int, m.groups())
+        if len(m.group(3)) == 2:
+            y += 2000 if y < 70 else 1900
+        if a > 12 or (day_first and b <= 12):
+            return _valid_date(y, b, a), a <= 12 and b <= 12 and a != b
+        return _valid_date(y, a, b), a <= 12 and b <= 12 and a != b
+    words = re.findall(r"[A-Za-z]+|\d+", text)
+    month = [MONTHS[w.lower()] for w in words if w.lower() in MONTHS]
+    numbers = [w for w in words if w.isdigit()]
+    years = [int(n) for n in numbers if len(n) == 4]
+    days = [int(n) for n in numbers if len(n) <= 2]
+    if len(month) == 1 and len(years) == 1 and len(days) == 1:
+        return _valid_date(years[0], month[0], days[0]), False
+    return None, False
+
+
+def as_time(value) -> str | None:
+    """Return HH:MM for inputs like 9:30, 9am, 9:30 PM, 21h30, 14:30:00, noon."""
+    if isinstance(value, (dt.time, dt.datetime)):
+        return value.strftime("%H:%M")
+    if not isinstance(value, str):
+        return None
+    text = value.strip().lower().replace(".", "")
+    if text in {"noon", "midday"}:
+        return "12:00"
+    if text == "midnight":
+        return "00:00"
+    iso = re.search(r"\d{4}-\d{2}-\d{2}[t\s](\d{2}:\d{2})", text)
+    if iso:
+        text = iso.group(1)
+    m = re.fullmatch(r"(\d{1,2})(?:\s*[:h]?\s*(\d{2}))?(?::\d{2}(?:\d+)?)?\s*(am|pm|a|p)?", text)
+    if not m:
+        return None
+    hour, minute, half = int(m.group(1)), int(m.group(2) or 0), m.group(3)
+    if half:
+        if not 1 <= hour <= 12:
+            return None
+        hour = hour % 12 + (12 if half.startswith("p") else 0)
+    if hour > 23 or minute > 59:
+        return None
+    return f"{hour:02d}:{minute:02d}"
+
+
+# ---------------------------------------------------------------- URLs
+
+_UNSAFE_SCHEMES = {"javascript", "data", "file", "vbscript", "about", "blob", "ftp", "chrome", "ms-settings"}
+
+
+def as_url(value) -> str | None:
+    """Absolute http(s) URL or None. Adds https:// to bare domains; never fetches."""
+    if isinstance(value, dict):
+        value = next((value[k] for k in ("url", "href", "src", "link") if k in value), None)
+    if not isinstance(value, str):
+        return None
+    text = value.strip().strip("<>\"'")
+    markdown = re.fullmatch(r"\[[^\]]*\]\((\S+?)\)", text)
+    if markdown:
+        text = markdown.group(1)
+    if text.startswith("//"):
+        text = "https:" + text
+    scheme = text.split(":", 1)[0].lower() if ":" in text else ""
+    if scheme in _UNSAFE_SCHEMES:
+        return None
+    if not re.match(r"https?://", text, re.I):
+        if re.match(r"(www\.)?[a-z0-9-]+(\.[a-z0-9-]+)*\.[a-z]{2,}(:\d+)?([/?#]|$)", text, re.I):
+            text = "https://" + text
+        else:
+            return None
+    if "\\" in text or re.search(r"[\x00-\x1f\x7f]", text):
+        return None
+    text = quote(text, safe=":/?#[]@!$&'()*+,;=%~-._")
+    try:
+        parts = urlsplit(text)
+        ok = parts.hostname and parts.username is None and parts.password is None and parts.port != 0
+    except ValueError:
+        ok = False
+    return text if ok else None
+
+
+# ---------------------------------------------------------------- request loading
+
+WRAPPER_KEYS = {"request", "card", "adaptivecard", "spec", "payload", "input", "args", "arguments",
+                "params", "parameters", "json", "requestjson", "cardjson", "content", "data", "ui"}
+
+
+def _repair_json(text: str) -> str:
+    """String-aware cleanup: comments, trailing commas, Python literals, single quotes."""
+    out, i, n = [], 0, len(text)
+    while i < n:
+        c = text[i]
+        if c in "\"'":
+            quote_char, j, chunk = c, i + 1, []
+            while j < n and text[j] != quote_char:
+                if text[j] == "\\" and j + 1 < n:
+                    chunk.append(text[j:j + 2])
+                    j += 2
+                    continue
+                chunk.append('\\"' if text[j] == '"' else text[j])
+                j += 1
+            body = "".join(chunk)
+            if quote_char == "'":
+                body = body.replace("\\'", "'")
+            out.append('"' + body + '"')
+            i = j + 1
+        elif text.startswith("//", i):
+            i = text.find("\n", i) if "\n" in text[i:] else n
+        elif text.startswith("/*", i):
+            end = text.find("*/", i + 2)
+            i = n if end < 0 else end + 2
+        elif c == ",":
+            j = i + 1
+            while j < n and text[j] in " \t\r\n":
+                j += 1
+            if j < n and text[j] in "}]":
+                i += 1
+            else:
+                out.append(c)
+                i += 1
+        elif c.isalpha():
+            m = re.match(r"[A-Za-z_]+", text[i:])
+            word = m.group(0)
+            out.append({"True": "true", "False": "false", "None": "null", "undefined": "null"}.get(word, word))
+            i += len(word)
+        else:
+            out.append(c)
+            i += 1
+    repaired = "".join(out)
+    # Close brackets left open by a truncated call (never an unterminated string).
+    stack, in_string, escape = [], False, False
+    for ch in repaired:
+        if in_string:
+            escape = not escape and ch == "\\"
+            if ch == '"' and not escape:
+                in_string = False
+            if ch != "\\":
+                escape = False
+        elif ch == '"':
+            in_string = True
+        elif ch in "[{":
+            stack.append("]" if ch == "[" else "}")
+        elif ch in "]}" and stack:
+            stack.pop()
+    if stack and not in_string:
+        repaired = repaired.rstrip().rstrip(",") + "".join(reversed(stack))
+    return repaired
+
+
+def parse_json_text(text: str, ctx: Context, path: str = "$"):
+    text = text.strip().lstrip("")
+    fenced = re.search(r"```(?:json|javascript|js)?\s*\n?([\s\S]*?)```", text, re.I)
+    if fenced:
+        text = fenced.group(1).strip()
+        ctx.fixed(path, "removed_code_fence")
+    if text[:1] not in "[{":
+        start = min([i for i in (text.find("{"), text.find("[")) if i >= 0], default=-1)
+        if start < 0:
+            raise CardError(path, "The request is not JSON. Send an object like "
+                            '{"title": "...", "elements": [{"type": "text", "text": "..."}]}.', "invalid_json")
+        text = text[start:]
+        ctx.fixed(path, "extracted_json_from_text")
+
+    def pairs_hook(items):
+        result = {}
+        for k, v in items:
+            if k in result:
+                ctx.fixed(path, "duplicate_key_last_wins", key=k)
+            result[k] = v
+        return result
+
+    def constant(_):
+        ctx.warn(path, "non_finite_number", "NaN/Infinity replaced by null.")
+        return None
+
+    decoder = json.JSONDecoder(object_pairs_hook=pairs_hook, parse_constant=constant)
+    for repaired in (False, True):
+        candidate = _repair_json(text) if repaired else text
+        try:
+            value, end = decoder.raw_decode(candidate)
+        except json.JSONDecodeError as exc:
+            if repaired:
+                raise CardError(path, f"Invalid JSON near line {exc.lineno}, column {exc.colno}: {exc.msg}. "
+                                "Send a JSON object with double-quoted keys.", "invalid_json") from None
+            continue
+        except (RecursionError, ValueError):
+            raise CardError(path, "JSON exceeds nesting or numeric limits.", "limit_exceeded") from None
+        if repaired:
+            ctx.fixed(path, "repaired_json_syntax")
+        if candidate[end:].strip():
+            ctx.fixed(path, "ignored_text_after_json")
+        return value
+    raise AssertionError("unreachable")
+
+
+def _json_compatible(value, ctx: Context, depth: int, seen: set, counter: list):
+    counter[0] += 1
+    if counter[0] > ctx.config.max_nodes or depth > ctx.config.max_depth + 10:
+        raise CardError("$", "Request exceeds node or nesting limits.", "limit_exceeded")
+    if isinstance(value, (dict, list, tuple, set, frozenset)):
+        if id(value) in seen:
+            raise CardError("$", "Circular data is not supported.", "invalid_shape")
+        seen = seen | {id(value)}
+        if len(value) > ctx.config.max_nodes:
+            raise CardError("$", "Request container is too large.", "limit_exceeded")
+        if isinstance(value, dict):
+            return {str(k): _json_compatible(v, ctx, depth + 1, seen, counter) for k, v in value.items()}
+        items = sorted(value, key=str) if isinstance(value, (set, frozenset)) else value
+        return [_json_compatible(v, ctx, depth + 1, seen, counter) for v in items]
+    if value is None or isinstance(value, (bool, int, str)):
+        if isinstance(value, str):
+            try:
+                value.encode("utf-8")
+            except UnicodeError:
+                value = value.encode("utf-8", "replace").decode("utf-8")
+                ctx.warn("$", "invalid_unicode", "Invalid Unicode characters were replaced.")
+        return value
+    if isinstance(value, float):
+        if math.isfinite(value):
+            return value
+        ctx.warn("$", "non_finite_number", "NaN/Infinity replaced by null.")
+        return None
+    if isinstance(value, (Decimal, Fraction)):
+        return float(value)
+    if isinstance(value, (dt.date, dt.datetime, dt.time)):
+        return value.isoformat()
+    raise CardError("$", f"Unsupported Python value of type {type(value).__name__}; use JSON data.", "invalid_shape")
+
+
+def load_request(value, ctx: Context):
+    """Accept dicts, lists, JSON strings (fenced, wrapped in prose, lightly broken)."""
+    for _ in range(3):
+        if not isinstance(value, str):
+            break
+        if len(value.encode("utf-8", "replace")) > ctx.config.max_payload_bytes:
+            raise CardError("$", "Request exceeds configured byte limit.", "limit_exceeded")
+        value = parse_json_text(value, ctx)
+    value = _json_compatible(value, ctx, 0, set(), [0])
+    encoded = json.dumps(value, ensure_ascii=False)
+    if len(encoded.encode("utf-8")) > ctx.config.max_payload_bytes:
+        raise CardError("$", "Request exceeds configured byte limit.", "limit_exceeded")
+    if not isinstance(value, (dict, list)):
+        if isinstance(value, str) and value.strip():
+            return {"elements": [value]}
+        raise CardError("$", 'Expected an object like {"title": "...", "elements": [...]}.', "invalid_shape")
+    return value