hyperweave 0.2.24__tar.gz → 0.2.26__tar.gz

{hyperweave-0.2.24 → hyperweave-0.2.26}/CHANGELOG.md

@@ -5,6 +5,34 @@ All notable changes to HyperWeave are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.26] - 2026-05-07
+
+Two follow-ups to v0.2.25's badge state architecture: strip status indicators now color correctly when CI metrics fail, and the snapshot test suite no longer fails on local-vs-CI version differences.
+
+### Fixed
+
+- **Strip status indicator color tracks the most severe CI metric** — a strip with `BUILD:failing` next to `STARS` and `VERSION` now renders the right-edge diamond red, matching pre-v0.2.25 behavior. The v0.2.25 narrowing inadvertently dropped this for strips because their title is the repo identifier (`HYPERWEAVE`, `readme-ai`), not a state-bearing label. The engine now parses strip metric cells, runs state inference per allowlisted cell (`BUILD`, `COVERAGE`, `LINT`, etc.), and rolls up to the most severe state across them. Pure data strips (no allowlisted cells) stay neutral.
+- **Snapshot tests handle local-vs-CI version differences** — the URL stability suite was treating package version strings as content (`version="0.2.20"` vs `version="0.2.25"` from dynamic git-tag versioning), failing CI when local snapshots were captured at a different version than the runner. Versions in metadata are now normalized for comparison alongside UUIDs and timestamps.
+
+### Notes
+
+- 960 tests (was 955). 5 new tests pin the strip rollup contract across failing / passing / mixed-severity / pure-data / explicit-override cases.
+
+## [0.2.25] - 2026-05-07
+
+Production badges on data-driven URLs (`STARS`, `FORKS`, `VERSION`, `LICENSE`, `PYTHON`) no longer trigger false-alarm status indicators on numeric values. Badge value text now centers correctly for every value length across all genomes.
+
+### Fixed
+
+- **Data badges no longer show false status indicators** — a `STARS` badge with value `6` rendered an orange warning diamond because the leading digit matched a threshold rule designed for percentages. Indicators now only appear on common build / test / CI / quality / deployment / monitoring titles (`BUILD`, `TESTS`, `CI`, `PIPELINE`, `WORKFLOW`, `COVERAGE`, `LINT`, `DEPLOY`, `RELEASE`, `STATUS`, `HEALTH`, `UPTIME`, etc.) or when explicitly set via `?state=`. Hyphen and underscore variants like `BUILD-STATUS` and `CI_CD` match the same canonical title without separate config entries.
+- **Badge value text centers correctly across all genomes** — values drifted 1–3px right of true center, with automata badges drifting further than chrome and brutalist. Centering now verified within 0.5px across short percentages, version strings, license slugs, python_requires, and long names.
+- **Monospace labels had extra padding on the right** — width measurement double-counted letter-spacing for mono labels like `BUILD` and `COVERAGE`; labels now match their actual rendered width.
+- **Data-only strips drop the status diamond** — `STARS | FORKS | VERSION` strips render as pure data; mixed strips like `BUILD | STARS` keep the right-edge indicator; `?state=` always overrides.
+
+### Notes
+
+- 955 tests (was 914). Divider and icon URLs render unchanged; existing badge URLs continue to work, with corrected centering and tighter widths where false indicators were removed.
+
 ## [0.2.24] - 2026-05-07
 
 Receipts no longer clip past the right edge of the card when one tool dominates the session. Cleanup pass removes an unused template, an unused styling table, and two silent default-position fallbacks in the receipt template.

{hyperweave-0.2.24 → hyperweave-0.2.26}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hyperweave
-Version: 0.2.24
+Version: 0.2.26
 Summary: Headless visual output layer for AI agents. One API call → self-contained SVG.
 Project-URL: Repository, https://github.com/InnerAura/hyperweave
 Project-URL: Issues, https://github.com/InnerAura/hyperweave/issues
@@ -51,6 +51,7 @@ Description-Content-Type: text/markdown
   <img src="https://hyperweave.app/v1/badge/PYTHON/chrome.static?data=pypi:hyperweave.python_requires" alt="python"/>
 </p>
 -->
+
 <p align="center">
   <img src="https://hyperweave.app/v1/strip/hyperweave/chrome.static?data=gh:InnerAura/hyperweave.build,pypi:hyperweave.version,gh:InnerAura/hyperweave.license&glyph=github" alt="strip"/>
 </p>

{hyperweave-0.2.24 → hyperweave-0.2.26}/README.md

@@ -19,6 +19,7 @@
   <img src="https://hyperweave.app/v1/badge/PYTHON/chrome.static?data=pypi:hyperweave.python_requires" alt="python"/>
 </p>
 -->
+
 <p align="center">
   <img src="https://hyperweave.app/v1/strip/hyperweave/chrome.static?data=gh:InnerAura/hyperweave.build,pypi:hyperweave.version,gh:InnerAura/hyperweave.license&glyph=github" alt="strip"/>
 </p>

{hyperweave-0.2.24 → hyperweave-0.2.26}/src/hyperweave/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.2.24'
-__version_tuple__ = version_tuple = (0, 2, 24)
+__version__ = version = '0.2.26'
+__version_tuple__ = version_tuple = (0, 2, 26)
 
 __commit_id__ = commit_id = None

{hyperweave-0.2.24 → hyperweave-0.2.26}/src/hyperweave/compose/context.py

@@ -117,6 +117,11 @@ def _base_context(
         "slots": [s.model_dump() for s in spec.slots],
         "numeric_value": spec.numeric_value,
         "data_hw_value": spec.numeric_value,
+        # v0.2.25: SVG-root attribute that gates threshold-CSS auto-tinting.
+        # Default "off" = stateless; resolvers override via frame_context.
+        # Values: "off" (stateless), "auto" (stateful, threshold-CSS may fire),
+        # "explicit" (?state= set; user owns the state, no auto-inference).
+        "data_hw_statemode": "off",
         # Profile
         "profile": profile,
         "badge_corner": profile.get("badge_corner", 3.33),

hyperweave-0.2.26/src/hyperweave/compose/engine.py

@@ -0,0 +1,167 @@
+"""Composition engine -- the single entry point for all artifact generation."""
+
+from __future__ import annotations
+
+import time
+
+from hyperweave.core.models import ArtifactMetadata, ComposeResult, ComposeSpec, ResolvedArtifact
+
+
+def compose(spec: ComposeSpec) -> ComposeResult:
+    """Compose an artifact from a ComposeSpec."""
+    start = time.monotonic()
+
+    # ── 0. Infer state from value when the caller left the default ──
+    # Any explicit override (?state=failing, --state passing, MCP state arg,
+    # etc.) sets spec.state to something other than "active" and survives
+    # this step untouched. This is the single chokepoint covering HTTP,
+    # CLI, MCP, and kit.
+    #
+    # v0.2.25: gated on the stateful-title allowlist (data/badge_modes.yaml).
+    # Pre-v0.2.25 the inference fired on EVERY frame regardless of title —
+    # so a STARS=42 badge was auto-inferred to state="critical" (leading
+    # digit 4) and rendered an orange/red status indicator on a value with
+    # no semantic state.
+    #
+    # Frame-aware logic:
+    #   Badge → title-keyed inference. Title in allowlist → run infer_state.
+    #   Strip → per-cell rolled-up inference. Strip's spec.title is the
+    #           repo identifier (HYPERWEAVE, readme-ai), not a state-
+    #           bearing label — state lives in the metric cells. Parse
+    #           cells, run infer_state on each allowlisted (label, value)
+    #           pair, take the most severe state.
+    if spec.state == "active" and spec.value:
+        from hyperweave.compose.layout import normalize_title
+        from hyperweave.config.loader import load_badge_modes
+        from hyperweave.core.enums import FrameType
+        from hyperweave.core.state import infer_state
+
+        allowlist = load_badge_modes()
+        # Severity ordering when rolling up across multiple metric cells.
+        # critical / failing share the most-severe slot — both render red.
+        _SEVERITY = {
+            "active": 0,
+            "passing": 1,
+            "building": 2,
+            "warning": 3,
+            "critical": 4,
+            "failing": 4,
+        }
+
+        inferred: str = "active"
+        if spec.type == FrameType.BADGE and spec.title:
+            if normalize_title(spec.title) in allowlist:
+                inferred = infer_state(spec.title, spec.value)
+        elif spec.type == FrameType.STRIP:
+            # Roll up across metric cells. v0.2.24 and earlier accidentally
+            # got this for free because infer_state ran on the strip's
+            # whole comma-separated value string and found "fail" in
+            # "BUILD:failing" — a happy substring-match accident. v0.2.25's
+            # title gate broke that path. Per-cell inference is the
+            # principled replacement: only allowlisted cells contribute
+            # state, and we pick the most severe.
+            best_severity = 0
+            for label, value in _parse_strip_metric_pairs(spec):
+                if normalize_title(label) in allowlist:
+                    cell_state = infer_state(label, value)
+                    sev = _SEVERITY.get(cell_state, 0)
+                    if sev > best_severity:
+                        inferred = cell_state
+                        best_severity = sev
+
+        if inferred != "active":
+            spec = spec.model_copy(update={"state": inferred})
+
+    # ── 1. Resolve genome, profile, frame ──
+    from hyperweave.compose.resolver import resolve
+
+    resolved = resolve(spec)
+
+    # ── 2. Assemble CSS ──
+    from hyperweave.compose.assembler import assemble_css
+
+    css_bundle = assemble_css(resolved, frame_type=spec.type)
+
+    # ── 3. Build template context ──
+    from hyperweave.compose.context import build_context
+
+    context = build_context(spec, resolved, css_bundle)
+
+    # ── 4. Enforce policy lanes ──
+    from hyperweave.compose.lanes import enforce
+
+    context = enforce(context, spec.regime)
+
+    # ── 5. Render template → SVG ──
+    from hyperweave.render.templates import render_artifact
+
+    svg = render_artifact(resolved.frame_template, context)
+
+    # ── 6. Build result ──
+    duration_ms = (time.monotonic() - start) * 1000
+
+    metadata = _build_metadata(spec, resolved, duration_ms)
+
+    result = ComposeResult(
+        svg=svg,
+        metadata=metadata,
+        width=resolved.width,
+        height=resolved.height,
+    )
+
+    # ── 7. Emit telemetry event (fire-and-forget) ──
+    try:
+        from hyperweave.telemetry.capture import emit_generation_event
+
+        emit_generation_event(spec, result)
+    except Exception:
+        pass  # telemetry must never break compose
+
+    return result
+
+
+def _parse_strip_metric_pairs(spec: ComposeSpec) -> list[tuple[str, str]]:
+    """Parse strip metric (label, value) pairs from spec.
+
+    Mirrors ``compose/resolver.py:_parse_metrics`` but lives here so engine
+    step 0 can run state inference before resolve() is called. Two sources:
+
+    * ``spec.slots`` entries with zones starting with ``metric`` —
+      ``slot.value`` of the form ``"LABEL:value"``.
+    * Comma-separated fallback in ``spec.value`` —
+      ``"STARS:2.9k,FORKS:278,BUILD:failing"``.
+    """
+    pairs: list[tuple[str, str]] = []
+    for slot in spec.slots:
+        if slot.zone.startswith("metric") and ":" in slot.value:
+            k, v = slot.value.split(":", 1)
+            pairs.append((k.strip(), v.strip()))
+    if not pairs and spec.value:
+        for pair_str in spec.value.split(","):
+            stripped = pair_str.strip()
+            if ":" in stripped:
+                k, v = stripped.split(":", 1)
+                pairs.append((k.strip(), v.strip()))
+    return pairs
+
+
+def _build_metadata(
+    spec: ComposeSpec,
+    resolved: ResolvedArtifact,
+    duration_ms: float,
+) -> ArtifactMetadata:
+    return ArtifactMetadata(
+        type=spec.type,
+        genome=spec.genome_id,
+        profile=resolved.profile_id,
+        divider_variant=spec.divider_variant,
+        motion=resolved.motion,
+        state=spec.state,
+        regime=spec.regime,
+        width=resolved.width,
+        height=resolved.height,
+        metadata_tier=spec.metadata_tier,
+        duration_ms=round(duration_ms, 2),
+        generation=spec.generation,
+        series=spec.series,
+    )

hyperweave-0.2.26/src/hyperweave/compose/layout.py

@@ -0,0 +1,303 @@
+"""Centralized spatial-layout engine for badge / strip frames (v0.2.25).
+
+Single source of truth for badge geometry. Replaces the inline arithmetic
+that lived in ``compose/resolver.py:resolve_badge`` (lines 270-354) and
+the duplicated geometry derivations in ``templates/frames/badge/*.j2``
+(brutalist's right_x/right_w, cellular's inner_w/inner_off, the per-
+template indicator_y duplicates).
+
+Per Invariant 6 (CLAUDE.md): templates render, compose computes geometry.
+Per ``feedback_compose_owns_geometry_template_renders.md``: layout
+decisions belong in compose/, not Jinja2.
+
+Two ``value_x`` regressions corrected by ``compute_badge_layout``:
+
+1. **Geometric centering, not midpoint of unrelated bounds.** The old
+   resolver used ``value_x = (right_x + val_pad_l + indicator_x) / 2``,
+   which is the midpoint of [value_zone_left, indicator_left_edge].
+   Indicator's left edge is val_min_gap inside the actual value-zone
+   right boundary. Result: text drifts ``val_min_gap/2 = 1.5px``
+   rightward. The new formula centers on the actual zone center.
+2. **No-indicator case is undefined under the old formula.** When the
+   indicator isn't rendered, ``indicator_x`` (still computed as
+   ``total_w - ind_pad_r - indicator_size``) lands *inside* or *left
+   of* the value text. The old midpoint averages two unrelated points.
+   The new formula uses ``total_w - val_min_gap`` as the right bound
+   when ``show_indicator=False`` and converges to a sane center.
+
+Three orthogonal helpers live here so all layout-and-mode decisions
+share a module:
+
+- ``compute_badge_layout`` — geometry only; pure function over input
+  measurements and paradigm constants.
+- ``resolve_badge_mode`` — three-mode classification
+  (stateful / stateless / explicit) keyed off the spec and a title
+  allowlist loaded from ``data/badge_modes.yaml``.
+- ``decide_strip_mode`` — same classification rolled up over a strip's
+  metric labels.
+
+The data-hw-statemode SVG-root attribute that gates threshold-CSS
+auto-tinting in ``data/css/expression.css`` is derived from the badge
+mode via ``data_hw_statemode_for``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Literal
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+    from hyperweave.core.models import ComposeSpec
+
+
+BadgeMode = Literal["stateful", "stateless", "explicit"]
+
+
+@dataclass(frozen=True)
+class BadgeLayout:
+    """Resolved spatial layout for a badge frame.
+
+    Templates consume these directly via ``{{ width }}``, ``{{ label_x }}``,
+    ``{{ value_x }}``, etc. — no template-side arithmetic. The
+    ``value_zone_*`` fields are exported for unit-test assertions.
+    """
+
+    width: int
+    height: int
+    label_x: float
+    value_x: float
+    glyph_x: int
+    glyph_y: float
+    indicator_x: float
+    indicator_y: float
+    indicator_size: int
+    left_panel_w: int
+    right_panel_x: int
+    right_panel_w: int
+    value_zone_left: float
+    value_zone_right: float
+    value_zone_width: float
+    text_y: float
+    show_indicator: bool
+    inner_bit_w: int
+    inner_bit_offset: float
+
+
+def compute_badge_layout(
+    *,
+    height: int,
+    measured_label_w: float,
+    measured_value_w: float,
+    has_glyph: bool,
+    show_indicator: bool,
+    use_mono: bool,
+    label_uppercase: bool,
+    value_raw_len: int,
+    accent_w: int,
+    inset: int,
+    glyph_size: int,
+    glyph_gap: int,
+    glyph_left_offset: int,
+    sep_w: int,
+    seam_w: int,
+    indicator_size: int,
+    ind_pad_r: int,
+    val_pad_l: int,
+    val_min_gap: int,
+    text_y_factor: float,
+    value_font_size: float,
+    right_canvas_inset: int = 0,
+    min_total_w: int = 60,
+) -> BadgeLayout:
+    """Compute every position the badge templates need from input measurements.
+
+    All positional fields in the returned ``BadgeLayout`` are measured
+    from the SVG origin (top-left). Geometry decisions (left/right panel
+    widths, indicator centering, glyph centering, value-zone centering)
+    are made here so all paradigms inherit the same correctness without
+    re-deriving in templates.
+
+    The centering correctness is verified by ``tests/test_badge_layout``
+    against short / long / version / license / python_requires values.
+    """
+    # Glyph pixel position. Mirrors resolver.py logic: paradigms with a
+    # left-edge decoration zone (cellular pattern strip x=2..~20) reserve
+    # space via ``glyph_left_offset``; brutalist/chrome declare 0.
+    if has_glyph:
+        glyph_x = (inset + accent_w + 4) if inset else (accent_w + 3)
+        glyph_x += glyph_left_offset
+        glyph_y = round((height - glyph_size) / 2, 1)
+    else:
+        glyph_x, glyph_y = 0, 0.0
+
+    # Label area starts after the glyph (or after the accent + paradigm
+    # left-edge decoration when there's no glyph). The no-glyph branch
+    # must respect glyph_left_offset too — cellular pattern strip runs
+    # to ~x=20 even when no glyph is rendered.
+    label_start = (glyph_x + glyph_size + glyph_gap) if has_glyph else (accent_w + 6 + glyph_left_offset)
+
+    # Left panel width — fits the label plus paradigm-driven right padding.
+    label_pad_r = 9 if use_mono else 8
+    left_panel = round(label_start + measured_label_w + label_pad_r)
+    left_panel = max(left_panel, 30)
+
+    # Label text center is the midpoint of the label area. For uppercase
+    # labels the visual right edge is 6px shy of the panel boundary so
+    # the cap glyphs don't kiss the seam.
+    label_area_end = left_panel - (6 if label_uppercase else 0)
+    label_x = round((label_start + label_area_end) / 2, 1)
+
+    # Right-panel allocation. ``ls_extra`` accounts for non-mono letter-
+    # spacing overrun (each char carries 0.4 of trailing tracking).
+    indicator_alloc = (indicator_size + ind_pad_r) if show_indicator else 0
+    ls_extra = value_raw_len * 0.4 if (not use_mono and value_raw_len) else 0
+    right_panel = val_pad_l + measured_value_w + ls_extra + 2 * val_min_gap + indicator_alloc
+    total_w = round(left_panel + sep_w + seam_w + right_panel)
+    total_w = max(total_w, min_total_w)
+
+    right_panel_x = left_panel + sep_w + seam_w
+    right_panel_w = total_w - right_panel_x
+
+    # Indicator position. Computed even when not shown — templates
+    # gate the actual rendering on ``show_indicator``; the value-zone
+    # center collapses to total_w-val_min_gap when the indicator is
+    # absent so the value text reclaims the freed space.
+    indicator_x = total_w - ind_pad_r - indicator_size
+
+    # Value-zone bounds — the heart of the v0.2.25 centering fix. The
+    # OLD resolver used ``(right_panel_x + val_pad_l + indicator_x) / 2``
+    # which is the midpoint of [zone_left, indicator_left_edge], not
+    # [zone_left, zone_right]. Old formula skewed text by val_min_gap/2
+    # toward the indicator and was undefined when no indicator rendered.
+    value_zone_left = right_panel_x + val_pad_l
+    # When stateless (no indicator), the slab's right edge is total_w minus
+    # any paradigm-specific canvas inset (cellular: 2; brutalist/chrome: 0).
+    # val_min_gap is the symmetric trailing pad — together they place
+    # value_zone_right at the slab's interior right boundary so a centered
+    # text lands at slab geometric center.
+    value_zone_right = (indicator_x - val_min_gap) if show_indicator else (total_w - right_canvas_inset - val_min_gap)
+    value_zone_width = value_zone_right - value_zone_left
+    value_x = round((value_zone_left + value_zone_right) / 2, 1)
+
+    text_y = round(height * text_y_factor, 1)
+    # Indicator vertical center pinned to value-text visual midline.
+    # cap_height ≈ 70% of font_size across the genome's display fonts
+    # (validated in data/font-metrics/), so visual_center = text_y -
+    # 0.3 * font_size. Indicator is square; top-y = visual_center -
+    # size/2. Single source of truth for vertical alignment across
+    # paradigms.
+    indicator_y = round(text_y - value_font_size * 0.3 - indicator_size / 2, 1)
+
+    # Indicator inner-bit geometry — moved from cellular/brutalist
+    # template-side arithmetic. The bit is half the indicator side,
+    # centered.
+    inner_bit_w = indicator_size // 2
+    inner_bit_offset = (indicator_size - inner_bit_w) / 2
+
+    return BadgeLayout(
+        width=total_w,
+        height=height,
+        label_x=label_x,
+        value_x=value_x,
+        glyph_x=glyph_x,
+        glyph_y=glyph_y,
+        indicator_x=indicator_x,
+        indicator_y=indicator_y,
+        indicator_size=indicator_size,
+        left_panel_w=left_panel,
+        right_panel_x=right_panel_x,
+        right_panel_w=right_panel_w,
+        value_zone_left=value_zone_left,
+        value_zone_right=value_zone_right,
+        value_zone_width=value_zone_width,
+        text_y=text_y,
+        show_indicator=show_indicator,
+        inner_bit_w=inner_bit_w,
+        inner_bit_offset=inner_bit_offset,
+    )
+
+
+# ─────────────────────────────────────────────────────────────────────
+# Three-mode state architecture
+# ─────────────────────────────────────────────────────────────────────
+
+
+def normalize_title(title: str | None) -> str:
+    """Lowercase + strip hyphens/underscores so allowlist lookup is
+    insensitive to common separator variants.
+
+    ``BUILD-STATUS`` → ``buildstatus``; ``CI_CD`` → ``cicd``. URL slashes
+    can't appear in path segments (they'd split into separate parts), so
+    we don't need slash handling. Empty / None → empty string.
+    """
+    if not title:
+        return ""
+    return title.lower().replace("-", "").replace("_", "")
+
+
+def resolve_badge_mode(spec: ComposeSpec, allowlist: frozenset[str]) -> BadgeMode:
+    """Classify a badge as stateful / stateless / explicit.
+
+    Three modes drive two orthogonal behaviors at render time:
+
+    * Indicator rendering: ``show_indicator = mode != "stateless"``
+    * Threshold-CSS auto-inference: gated by ``data-hw-statemode="auto"``
+      on the SVG root, which fires only for ``stateful`` (auto-inferred
+      from leading-digit value). ``stateless`` and ``explicit`` skip it.
+
+    Title lookup normalizes via ``normalize_title`` (lowercase, strip
+    hyphens/underscores) so ``BUILD-STATUS`` and ``BUILD_STATUS`` both
+    match the canonical ``buildstatus`` allowlist entry without bloating
+    the YAML with every separator variant.
+
+    Note on ``spec.state == "active"``: ComposeSpec defaults ``state`` to
+    the truthy sentinel ``"active"`` (Pydantic default in
+    core/models.py:98), NOT empty string. Treat that sentinel as "user
+    did not opine" — fall through to the allowlist check. Any other
+    value (including ``"active"`` if explicitly re-set, which is fine)
+    means the caller asked for a specific state → explicit mode.
+    """
+    if spec.state and spec.state != "active":
+        return "explicit"
+    title = normalize_title(spec.title)
+    if title and title in allowlist:
+        return "stateful"
+    return "stateless"
+
+
+def decide_strip_mode(
+    metric_titles: Iterable[str | None],
+    spec: ComposeSpec,
+    allowlist: frozenset[str],
+) -> BadgeMode:
+    """Roll up the strip's mode from its metric cells' titles.
+
+    Strip's right-edge indicator is the strip's overall health pixel.
+    If ANY metric is stateful, the indicator renders with rolled-up
+    state. Stateless cells coexist; per-cell indicators were already
+    rejected (memory: ``feedback_strip_single_diamond.md``).
+
+    Metric titles are normalized via ``normalize_title`` for the same
+    reasons as ``resolve_badge_mode`` — ``BUILD-STATUS`` cell matches
+    the same canonical ``buildstatus`` allowlist entry.
+    """
+    if spec.state and spec.state != "active":
+        return "explicit"
+    for title in metric_titles:
+        if title and normalize_title(title) in allowlist:
+            return "stateful"
+    return "stateless"
+
+
+def data_hw_statemode_for(mode: BadgeMode) -> str:
+    """Map ``BadgeMode`` to the SVG-root ``data-hw-statemode`` attribute value.
+
+    The CSS in ``data/css/expression.css`` qualifies its threshold
+    selectors with ``[data-hw-statemode="auto"]`` so auto-inference
+    only applies to ``stateful``. ``stateless`` ("off") and ``explicit``
+    ("explicit") bypass auto-tinting; explicit-mode badges still get
+    state colors via the ``[data-hw-status="..."]`` cascade.
+    """
+    return {"stateful": "auto", "explicit": "explicit", "stateless": "off"}[mode]