hyperweave 0.3.2__tar.gz → 0.3.4__tar.gz

{hyperweave-0.3.2 → hyperweave-0.3.4}/CHANGELOG.md

@@ -5,6 +5,44 @@ 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.3.4] - 2026-05-13
+
+`install-hook` now detects Claude Code and Codex automatically. A new `hyperweave doctor` command shows hook status, transcripts, and recent receipts at a glance.
+
+### Added
+
+- **`hyperweave doctor`** — shows hook registration, transcript directories, recent receipts, and version info per runtime.
+- **`install-hook --runtime all`** — registers hooks for both runtimes regardless of auto-detection.
+
+### Changed
+
+- **`install-hook` default** — without `--runtime`, detects which runtimes are installed and registers hooks for each. `--runtime claude-code` or `--runtime codex` scopes to one.
+
+### Fixed
+
+- **Receipt footer** — restores the full relative path (`.hyperweave/receipts/{slug}.svg`); v0.3.3 had stripped the directory prefix.
+
+### Notes
+
+- Codex receipts refresh live as the session progresses, reflecting cumulative state after each turn.
+
+## [0.3.3] - 2026-05-12
+
+### Fixed
+
+- **Receipt filenames** — use consistent underscore separators; the footer displays the same human-readable filename.
+- **Dark brutalist badge panels** — match the prototype: left panel reads `brand_panel_fill`, label reads `ink-primary`, seam-gap rect restored so the divider region renders the same in any markdown viewer.
+- **Badge layout engine** — brutalist badges land every interior gap (accent→glyph, glyph→label, label→seam, seam→value, value→indicator, indicator→right border) on a single 5px rhythm. `measure_text` now consumes the paradigm's declared `value_letter_spacing_em` so the engine reserves the actual rendered width instead of under-counting by `(n-1) * font_size * em`.
+- **Dark brutalist star charts** — header glyph fill routes through `var(--dna-signal)` (was an orphaned brand-text white). 6px solid left accent rail anchors the chart as a Y-axis spine; outer perimeter softens to a 1.5px hairline at 0.25 opacity so the rail dominates the read.
+- **Light scholar star charts** — area gradient resolves through each variant's panel color across all 6 light variants instead of falling back to the seam color. Substrate-aware paper grain with multiply blend; perimeter inset and grain layer order match the prototype.
+- **Activity graph bars** — light scholar stat cards use the correct accent color.
+- **Divider tick marks** — resolve through the genome palette instead of a hardcoded green.
+
+### Changed
+
+- **Star chart milestone callouts** — now include date context (e.g. `1K · JAN 24`) so the chart is self-documenting without cross-referencing external star history tools.
+- **Star chart milestone markers** — data points use a filled square marker (■) to visually distinguish them from the regular interval crosshair (+) markers.
+
 ## [0.3.2] - 2026-05-11
 
 Brutalist gets 12 variants split by substrate: 6 dark monochromes (celadon, carbon, alloy, temper, pigment, ember) and 6 light scholars (archive, signal, pulse, depth, afterimage, primer). Metadata pipeline wires 12 fields that were silently hardcoded. Per-frame reasoning populates `hw:reasoning` from per-genome YAML.

{hyperweave-0.3.2 → hyperweave-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hyperweave
-Version: 0.3.2
+Version: 0.3.4
 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
@@ -197,11 +197,11 @@ Why genome and not theme? Because brand isn't a design problem, it's an infrastr
 <tr>
 <th align="left">Dashboard<br/><sub>strip</sub></th>
 <td>
-  <img src="https://hyperweave.app/v1/strip/readme-ai/brutalist.static?data=gh:eli64s/readme-ai.stars,gh:eli64s/readme-ai.forks,pypi:readmeai.version&subtitle=eli64s/readme-ai&glyph=github&variant=celadon" alt="strip"/>
+  <img src="https://hyperweave.app/v1/strip/hyperweave/brutalist.static?data=gh:InnerAura/hyperweave.stars,pypi:hyperweave.version,gh:InnerAura/hyperweave.build&subtitle=InnerAura/hyperweave&glyph=github&variant=celadon" alt="strip"/>
   <br/>
   <ul>
 <li><sub><code>/v1/strip/{title}/{genome}.static?data={tokens}&subtitle={text}&glyph={glyph}&variant={variant}</code></sub></li>
-<li><sub><code>hyperweave.app/v1/strip/readme-ai/brutalist.static?data=gh:eli64s/readme-ai.stars,gh:eli64s/readme-ai.forks,pypi:readmeai.version&subtitle=eli64s/readme-ai&glyph=github&variant=celadon</code></sub></li>
+<li><sub><code>hyperweave.app/v1/strip/hyperweave/brutalist.static?data=gh:InnerAura/hyperweave.stars,pypi:hyperweave.version,gh:InnerAura/hyperweave.build&subtitle=InnerAura/hyperweave&glyph=github&variant=celadon</code></sub></li>
 </ul>
 </td>
 </tr>

{hyperweave-0.3.2 → hyperweave-0.3.4}/README.md

@@ -165,11 +165,11 @@ Why genome and not theme? Because brand isn't a design problem, it's an infrastr
 <tr>
 <th align="left">Dashboard<br/><sub>strip</sub></th>
 <td>
-  <img src="https://hyperweave.app/v1/strip/readme-ai/brutalist.static?data=gh:eli64s/readme-ai.stars,gh:eli64s/readme-ai.forks,pypi:readmeai.version&subtitle=eli64s/readme-ai&glyph=github&variant=celadon" alt="strip"/>
+  <img src="https://hyperweave.app/v1/strip/hyperweave/brutalist.static?data=gh:InnerAura/hyperweave.stars,pypi:hyperweave.version,gh:InnerAura/hyperweave.build&subtitle=InnerAura/hyperweave&glyph=github&variant=celadon" alt="strip"/>
   <br/>
   <ul>
 <li><sub><code>/v1/strip/{title}/{genome}.static?data={tokens}&subtitle={text}&glyph={glyph}&variant={variant}</code></sub></li>
-<li><sub><code>hyperweave.app/v1/strip/readme-ai/brutalist.static?data=gh:eli64s/readme-ai.stars,gh:eli64s/readme-ai.forks,pypi:readmeai.version&subtitle=eli64s/readme-ai&glyph=github&variant=celadon</code></sub></li>
+<li><sub><code>hyperweave.app/v1/strip/hyperweave/brutalist.static?data=gh:InnerAura/hyperweave.stars,pypi:hyperweave.version,gh:InnerAura/hyperweave.build&subtitle=InnerAura/hyperweave&glyph=github&variant=celadon</code></sub></li>
 </ul>
 </td>
 </tr>

{hyperweave-0.3.2 → hyperweave-0.3.4}/src/hyperweave/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.3.2'
-__version_tuple__ = version_tuple = (0, 3, 2)
+__version__ = version = '0.3.4'
+__version_tuple__ = version_tuple = (0, 3, 4)
 
 __commit_id__ = commit_id = None

{hyperweave-0.3.2 → hyperweave-0.3.4}/src/hyperweave/cli.py

@@ -361,39 +361,56 @@ def session(
 
     frame_type = "receipt" if action == "receipt" else "rhythm-strip"
     genome_slug = _normalize_genome_slug(genome) if genome else ""
+
+    # Pre-compute the receipt's on-disk filename (when applicable) so the
+    # footer can render the same path as the file the user sees. The compose
+    # pipeline reads receipt_filename_hint when set; an empty hint falls back
+    # to the legacy UUID-path footer (HTTP / MCP). Pass the FULL relative
+    # path (not just the basename) so the footer is self-documenting — a
+    # reader sees ".hyperweave/receipts/{slug}.svg" and knows where to find
+    # the file without prior context. Long footers trigger left-truncation
+    # of the constant prefix at resolver.py:_truncate_path_left.
+    filename_hint = ""
+    if action == "receipt" and not output:
+        from datetime import datetime as _dt
+
+        from hyperweave.telemetry.receipt_paths import receipt_filename
+
+        sess = contract.get("session", {})
+        sid = sess.get("id", "unknown")
+        session_name = sess.get("name", "")
+        start_iso = sess.get("start", "")
+        try:
+            ts = _dt.fromisoformat(start_iso)
+        except (TypeError, ValueError):
+            ts = _dt.now()
+        user_events = contract.get("user_events", []) or []
+        first_prompt = user_events[0].get("preview", "") if user_events else ""
+        hw_dir = Path(".hyperweave") / "receipts"
+        hw_dir.mkdir(parents=True, exist_ok=True)
+        output = hw_dir / receipt_filename(
+            timestamp=ts,
+            session_name=session_name,
+            session_id=sid,
+            prompt_text=first_prompt,
+        )
+        filename_hint = str(output)
+    elif action == "receipt" and output:
+        # Explicit --output: surface whatever path shape the user provided.
+        filename_hint = str(output)
+
     spec = ComposeSpec(
         type=frame_type,
         genome_id=genome_slug,
         telemetry_data=contract,
+        receipt_filename_hint=filename_hint,
     )
     result = do_compose(spec)
 
     if action == "receipt":
-        # Default output: .hyperweave/receipts/{date}_{time}_{slug}.svg
-        if not output:
-            from datetime import datetime as _dt
-
-            from hyperweave.telemetry.receipt_paths import receipt_filename
-
-            sess = contract.get("session", {})
-            sid = sess.get("id", "unknown")
-            session_name = sess.get("name", "")
-            start_iso = sess.get("start", "")
-            try:
-                ts = _dt.fromisoformat(start_iso)
-            except (TypeError, ValueError):
-                ts = _dt.now()
-            user_events = contract.get("user_events", []) or []
-            first_prompt = user_events[0].get("preview", "") if user_events else ""
-            hw_dir = Path(".hyperweave") / "receipts"
-            hw_dir.mkdir(parents=True, exist_ok=True)
-            output = hw_dir / receipt_filename(
-                timestamp=ts,
-                session_name=session_name,
-                session_id=sid,
-                prompt_text=first_prompt,
-            )
-
+        # output is guaranteed non-None here: the receipt branch above either
+        # received an explicit --output or computed a default path.
+        assert output is not None
         output.parent.mkdir(parents=True, exist_ok=True)
         output.write_text(result.svg)
 
@@ -554,12 +571,13 @@ def _install_codex_hook(hook_command: str, full_slug: str) -> None:
     """Write a Stop hook to ``~/.codex/hooks.json`` + enable codex_hooks feature.
 
     Per developers.openai.com/codex/hooks, Codex CLI fires Stop hooks
-    PER-TURN (not per-session). Receipts therefore render at every turn
-    boundary rather than once at session end. Document this caveat
-    prominently — users may want to manually invoke
-    ``hyperweave session receipt <transcript-path>`` once a session
-    completes instead. v0.2.24 will revisit when codex notify-config
-    surfaces a session-scoped event.
+    PER-TURN (after every assistant response). The receipt rewrites the
+    same deterministic filename each turn, so the on-disk file becomes a
+    live mid-session telemetry window — opening it during a long session
+    shows the current state, and the final write at session-end carries
+    the complete cumulative receipt. This is intentional; future versions
+    will lean into live-receipt consumers (file watchers, dashboards)
+    rather than collapse it back to a single session-end event.
 
     Also writes ``[features] codex_hooks = true`` to ``~/.codex/config.toml``
     (preserving any other keys); the feature flag is required for the
@@ -615,8 +633,8 @@ def _install_codex_hook(hook_command: str, full_slug: str) -> None:
     typer.echo(f"Installed Stop hook in {hooks_path}{pinned}")
     typer.echo(f"Set [features] codex_hooks = true in {config_path}")
     typer.echo(
-        "Note: Codex Stop fires per-turn — receipts render multiple times per session. "
-        "v0.2.24 will refine to a session-scoped event.",
+        "Note: Codex Stop fires per-turn — the receipt file refreshes live as the "
+        "session progresses, always reflecting current cumulative state.",
         err=True,
     )
 
@@ -630,6 +648,37 @@ _HOOK_INSTALLERS = {
     "codex": _install_codex_hook,
 }
 
+# Runtime → (config_dirname_under_home, cli_binary_name). Drives both the
+# auto-detect path (config dir OR binary on PATH) and `hyperweave doctor`
+# state reporting. Config-dir presence means "agent has been run at least
+# once"; binary-on-PATH covers fresh installs where the dir hasn't been
+# created yet. The installers create their dirs on demand, so installing
+# for a binary-only runtime is safe.
+_RUNTIME_DETECTION = {
+    "claude-code": (".claude", "claude"),
+    "codex": (".codex", "codex"),
+}
+
+
+def _detect_installed_runtimes() -> list[tuple[str, str]]:
+    """Detect installed agent runtimes via config-dir-OR-binary-on-PATH.
+
+    Returns ``(runtime_key, signal)`` tuples in ``_RUNTIME_DETECTION`` order.
+    Signal is ``"initialized"`` when the runtime's config dir exists (agent
+    has been run at least once), ``"binary_only"`` when only the CLI is on
+    PATH (fresh install, config dir not created yet). Runtimes with
+    neither signal are omitted entirely.
+    """
+    import shutil
+
+    detected: list[tuple[str, str]] = []
+    for runtime, (dirname, binname) in _RUNTIME_DETECTION.items():
+        if (Path.home() / dirname).exists():
+            detected.append((runtime, "initialized"))
+        elif shutil.which(binname):
+            detected.append((runtime, "binary_only"))
+    return detected
+
 
 @app.command("install-hook")
 def install_hook(
@@ -649,28 +698,55 @@ def install_hook(
         typer.Option(
             "--runtime",
             help=(
-                "Agent runtime to install the receipt hook for. 'claude-code' (default) "
-                "writes a SessionEnd hook to ~/.claude/settings.json. 'codex' writes a "
-                "Stop hook to ~/.codex/hooks.json plus enables [features] codex_hooks "
-                "in ~/.codex/config.toml. Codex Stop is per-turn, not per-session — "
-                "see release notes for caveats."
+                "Agent runtime to install the receipt hook for. Empty (default) "
+                "auto-detects installed runtimes (~/.claude, ~/.codex, or 'claude'/"
+                "'codex' on PATH) and registers for each present. 'claude-code' "
+                "writes a SessionEnd hook to ~/.claude/settings.json. 'codex' writes "
+                "a Stop hook to ~/.codex/hooks.json plus [features] codex_hooks in "
+                "~/.codex/config.toml. 'all' forces both regardless of detection."
             ),
         ),
-    ] = "claude-code",
+    ] = "",
 ) -> None:
-    """Install a session-receipt hook for the chosen agent runtime."""
+    """Install session-receipt hooks for installed agent runtimes.
+
+    Default behavior detects which agent CLIs are installed (Claude Code,
+    Codex) via config dir presence or binary on PATH, and registers receipt
+    hooks for each. Pass ``--runtime <name>`` to scope to a single runtime,
+    or ``--runtime all`` to force both regardless of detection.
+    """
     from hyperweave.compose.resolver import _genome_supports_receipts
 
-    if runtime not in _HOOK_INSTALLERS:
+    # Resolve targets:
+    #   ""     (default) → auto-detect installed runtimes (config dir OR binary)
+    #   "all"            → both runtimes regardless of detection
+    #   "<name>"         → just that runtime (legacy explicit form)
+    if runtime == "":
+        detected = _detect_installed_runtimes()
+        if not detected:
+            typer.echo(
+                "Error: no agent runtime detected (~/.claude, ~/.codex, or "
+                "'claude'/'codex' on PATH). Install Claude Code or Codex CLI, "
+                "or pass --runtime <name> to force.",
+                err=True,
+            )
+            raise typer.Exit(1)
+        targets = [rt for rt, _signal in detected]
+    elif runtime == "all":
+        targets = list(_HOOK_INSTALLERS)
+    elif runtime in _HOOK_INSTALLERS:
+        targets = [runtime]
+    else:
         typer.echo(
-            f"Error: unknown runtime '{runtime}'. Supported: {sorted(_HOOK_INSTALLERS)}",
+            f"Error: unknown runtime '{runtime}'. Supported: {sorted(_HOOK_INSTALLERS)} or 'all'.",
             err=True,
         )
         raise typer.Exit(1)
 
-    # Validate --genome BEFORE writing the hook. install-hook fails loud (unlike
-    # the receipt CLI which silently falls through) because pinning a bad genome
-    # would produce silent surprises every session-end until someone notices.
+    # Validate --genome BEFORE writing any hook. install-hook fails loud
+    # (unlike the receipt CLI which silently falls through) because pinning
+    # a bad genome would produce silent surprises every session-end until
+    # someone notices. Validate once even when targeting multiple runtimes.
     full_slug = ""
     if genome:
         full_slug = _normalize_genome_slug(genome)
@@ -685,7 +761,151 @@ def install_hook(
 
     hook_command = f"hyperweave session receipt --genome {full_slug}" if full_slug else "hyperweave session receipt"
 
-    _HOOK_INSTALLERS[runtime](hook_command, full_slug)
+    for target in targets:
+        _HOOK_INSTALLERS[target](hook_command, full_slug)
+
+
+def _doctor_runtime_status(runtime: str, home_dir: Path) -> str:
+    """Parse a runtime's hook config and return a one-line status string.
+
+    Returns ``✓`` when the hyperweave hook is wired correctly, ``✗`` when
+    the runtime is initialized but no hyperweave hook is registered, or
+    ``⚠`` when the wiring is partial (malformed config; codex missing the
+    [features] codex_hooks flag). The string is rendered verbatim by
+    ``doctor``.
+    """
+    import json
+
+    if runtime == "claude-code":
+        settings_path = home_dir / "settings.json"
+        if not settings_path.exists():
+            return (
+                f"✗ {runtime}: ~/.claude/ exists but no settings.json — "
+                f"run 'hyperweave install-hook --runtime {runtime}'"
+            )
+        try:
+            settings = json.loads(settings_path.read_text())
+        except json.JSONDecodeError:
+            return f"⚠ {runtime}: ~/.claude/settings.json is malformed"
+        for entry in settings.get("hooks", {}).get("SessionEnd", []) or []:
+            if not isinstance(entry, dict):
+                continue
+            for hook in entry.get("hooks", []) or []:
+                if not isinstance(hook, dict):
+                    continue
+                cmd = str(hook.get("command", ""))
+                if "hyperweave session" in cmd:
+                    return f"✓ {runtime}: hook registered — {cmd}"
+        return f"✗ {runtime}: initialized but no hyperweave hook — run 'hyperweave install-hook --runtime {runtime}'"
+
+    if runtime == "codex":
+        hooks_path = home_dir / "hooks.json"
+        config_path = home_dir / "config.toml"
+        registered_cmd: str | None = None
+        if hooks_path.exists():
+            try:
+                hooks = json.loads(hooks_path.read_text())
+            except json.JSONDecodeError:
+                return f"⚠ {runtime}: ~/.codex/hooks.json is malformed"
+            for entry in hooks.get("Stop", []) or []:
+                if not isinstance(entry, dict):
+                    continue
+                cmd = str(entry.get("command", ""))
+                if "hyperweave session" in cmd:
+                    registered_cmd = cmd
+                    break
+        if not registered_cmd:
+            return (
+                f"✗ {runtime}: initialized but no hyperweave hook — run 'hyperweave install-hook --runtime {runtime}'"
+            )
+        # [features] codex_hooks = true must be present for the hook to fire;
+        # the install command writes it, but a hand-edited config could miss it.
+        feature_ok = False
+        if config_path.exists():
+            in_features = False
+            for line in config_path.read_text().splitlines():
+                stripped = line.strip()
+                if stripped == "[features]":
+                    in_features = True
+                    continue
+                if in_features and stripped.startswith("["):
+                    in_features = False
+                    continue
+                if in_features and stripped.startswith("codex_hooks") and "true" in stripped:
+                    feature_ok = True
+                    break
+        if not feature_ok:
+            return (
+                f"⚠ {runtime}: hook registered but [features] codex_hooks = true "
+                f"is missing — re-run 'hyperweave install-hook --runtime {runtime}'"
+            )
+        return f"✓ {runtime}: hook registered — {registered_cmd}"
+
+    return f"? {runtime}: unknown runtime"
+
+
+@app.command()
+def doctor() -> None:
+    """Diagnose hyperweave telemetry wiring across agent runtimes.
+
+    Reports per-runtime detection state (initialized / binary-only /
+    absent), hook registration status, transcript dir state, and recent
+    receipt activity in the current directory. Read-only — never
+    modifies any config. Always exits 0.
+    """
+    import shutil
+    from datetime import datetime, timedelta
+
+    from hyperweave import __version__
+
+    typer.echo(f"hyperweave doctor — v{__version__}")
+    typer.echo("")
+    typer.echo("Runtimes:")
+    for runtime, (dirname, binname) in _RUNTIME_DETECTION.items():
+        home_dir = Path.home() / dirname
+        if home_dir.exists():
+            typer.echo(f"  {_doctor_runtime_status(runtime, home_dir)}")
+        elif bin_path := shutil.which(binname):
+            typer.echo(
+                f"  ⚠ {runtime}: CLI on PATH at {bin_path} but ~/{dirname}/ "
+                f"not initialized — run '{binname}' once, then "
+                f"'hyperweave install-hook --runtime {runtime}'"
+            )
+        else:
+            typer.echo(f"  ✗ {runtime}: not detected")
+
+    typer.echo("")
+    typer.echo("Transcripts:")
+    for runtime, subdir in (("claude-code", "projects"), ("codex", "sessions")):
+        dirname = _RUNTIME_DETECTION[runtime][0]
+        root = Path.home() / dirname / subdir
+        display_root = f"~/{dirname}/{subdir}"
+        if not root.exists():
+            typer.echo(f"  {runtime}: {display_root} (not found)")
+            continue
+        files = list(root.rglob("*.jsonl"))
+        if not files:
+            typer.echo(f"  {runtime}: {display_root}/ (empty)")
+            continue
+        most_recent = max(files, key=lambda p: p.stat().st_mtime)
+        mtime = datetime.fromtimestamp(most_recent.stat().st_mtime)
+        typer.echo(f"  {runtime}: {len(files)} transcript(s), most recent {mtime:%Y-%m-%d %H:%M}")
+
+    typer.echo("")
+    typer.echo("Receipts (./.hyperweave/receipts/):")
+    receipts_dir = Path(".hyperweave") / "receipts"
+    if not receipts_dir.exists():
+        typer.echo("  (no receipts directory in cwd)")
+        return
+    svgs = [p for p in receipts_dir.iterdir() if p.is_file() and p.suffix == ".svg"]
+    if not svgs:
+        typer.echo("  (no receipts)")
+        return
+    cutoff = datetime.now() - timedelta(days=7)
+    recent = [p for p in svgs if datetime.fromtimestamp(p.stat().st_mtime) > cutoff]
+    most_recent = max(svgs, key=lambda p: p.stat().st_mtime)
+    typer.echo(f"  {len(recent)} receipt(s) in last 7 days, {len(svgs)} total")
+    typer.echo(f"  most recent: {most_recent.name}")
 
 
 @app.command("validate-genome")

{hyperweave-0.3.2 → hyperweave-0.3.4}/src/hyperweave/compose/layout.py

@@ -110,6 +110,8 @@ def compute_badge_layout(
     value_font_size: float,
     right_canvas_inset: int = 0,
     min_total_w: int = 60,
+    inner_bit_ratio: float = 0.5,
+    rhythm_gap: int = 0,
 ) -> BadgeLayout:
     """Compute every position the badge templates need from input measurements.
 
@@ -121,44 +123,83 @@ def compute_badge_layout(
 
     The centering correctness is verified by ``tests/test_badge_layout``
     against short / long / version / license / python_requires values.
+
+    When ``rhythm_gap > 0`` (brutalist v0.3.3 sets 8), the layout collapses
+    every interior gap to a single value: accent_right→glyph_left,
+    glyph_right→label_first, label_last→seam_left, seam_right→value_first,
+    value_last→indicator_left, indicator_right→right_border. Caller must
+    also set ``ind_pad_r=rhythm_gap`` so the indicator gaps land on the
+    same rhythm.
     """
     # 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.
+    # When rhythm_gap is set, the glyph sits exactly ``rhythm_gap`` right
+    # of the accent bar so the accent→glyph gap matches the global rhythm.
     if has_glyph:
-        glyph_x = (inset + accent_w + 4) if inset else (accent_w + 3)
-        glyph_x += glyph_left_offset
+        if rhythm_gap > 0:
+            glyph_x = accent_w + rhythm_gap + glyph_left_offset
+        else:
+            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-edge decoration when there's no glyph). When rhythm_gap > 0,
+    # the glyph→label gap (with-glyph) and accent→label gap (no-glyph)
+    # both equal rhythm_gap.
+    if rhythm_gap > 0:
+        label_start = (glyph_x + glyph_size + rhythm_gap) if has_glyph else (accent_w + rhythm_gap + glyph_left_offset)
+    else:
+        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
+    # rhythm_gap mode forces label_pad_r = rhythm_gap so label_last→seam_left
+    # equals the global rhythm. Legacy mode keeps the 9 (mono) / 8 (non-mono)
+    # default tuned for chrome/cellular's denser label kerning.
+    label_pad_r = rhythm_gap if rhythm_gap > 0 else (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)
+    # Label text center. Legacy mode centers the label in [label_start,
+    # label_area_end] with a 6px shy-from-seam adjustment for uppercase
+    # labels. rhythm_gap mode aligns label_first with label_start exactly
+    # (label_x = label_start + w/2) so the accent_right→label_first gap
+    # lands at ``rhythm_gap`` regardless of label_w. The legacy area-center
+    # formula leaves a (panel_w - label_w)/2 interior gutter inside the
+    # label area, which collapses the structural gap to ~(rhythm_gap +
+    # interior_gutter)/2 — visible as 12.2/4.2 asymmetry on a 35.64px
+    # label in a 44px area when targeting an 8px rhythm.
+    if rhythm_gap > 0:
+        label_area_end = left_panel
+        label_x = round(label_start + measured_label_w / 2, 1)
+    else:
+        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 reserves: val_pad_l (left interior gutter), the measured
-    # value text + letter-spacing overrun, val_min_gap (right interior gutter),
-    # and indicator_alloc when stateful. Pre-v0.3.0 reserved 2 * val_min_gap
-    # which left ~val_min_gap of unaccounted slack on stateless badges
-    # (visible as ~4.5px right padding instead of symmetric ~3px).
-    right_panel = val_pad_l + measured_value_w + ls_extra + val_min_gap + indicator_alloc
+    # Gap between value text right edge and the indicator's left edge. For
+    # stateful badges this mirrors ``ind_pad_r`` (gap right of indicator) so
+    # the indicator sits with equal interior padding on both sides — the
+    # cohesive-balance contract the brutalist v16 prototype encodes. For
+    # stateless badges there's no indicator, so the trailing pad collapses
+    # to ``val_min_gap`` (3px tight right gutter; tighter than the stateful
+    # symmetric gap because there's no marker to balance against).
+    text_to_indicator_gap = ind_pad_r if show_indicator else val_min_gap
+    # rhythm_gap mode overrides ``val_pad_l`` (seam→value gap) to the
+    # global rhythm. Legacy mode keeps the resolver-supplied val_pad_l
+    # (3px) for chrome/cellular/default paradigms.
+    effective_val_pad_l = rhythm_gap if rhythm_gap > 0 else val_pad_l
+    # right_panel reserves: effective_val_pad_l (left interior gutter), the
+    # measured value text + letter-spacing overrun, text_to_indicator_gap
+    # (right interior gutter), and indicator_alloc when stateful. Symmetric
+    # stateful: text + ind_pad_r + indicator_size + ind_pad_r.
+    right_panel = effective_val_pad_l + measured_value_w + ls_extra + text_to_indicator_gap + indicator_alloc
     total_w = round(left_panel + sep_w + seam_w + right_panel)
     total_w = max(total_w, min_total_w)
 
@@ -176,13 +217,14 @@ def compute_badge_layout(
     # 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
+    value_zone_left = right_panel_x + effective_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)
+    # any paradigm-specific canvas inset (cellular: 2; brutalist/chrome: 0)
+    # minus val_min_gap (tight 3px trailing pad). When stateful, the right
+    # edge sits ind_pad_r inside the indicator's left edge — mirroring the
+    # right-of-indicator gap so the indicator reads as equidistant from
+    # the value text and from the badge's right border.
+    value_zone_right = (indicator_x - ind_pad_r) 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)
 
@@ -196,9 +238,12 @@ def compute_badge_layout(
     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
+    # template-side arithmetic. v0.3.3 generalizes the ratio so brutalist
+    # can render the prototype's 6/10 (0.6) bit instead of the cellular
+    # 4/8 (0.5) default — caller passes a paradigm-driven ratio. Rounded
+    # to the nearest integer so the bit lands on a pixel grid; offset is
+    # the half-difference, which can be a half-pixel for odd ratios.
+    inner_bit_w = round(indicator_size * inner_bit_ratio)
     inner_bit_offset = (indicator_size - inner_bit_w) / 2
 
     return BadgeLayout(