feat: first draft at kirin kernel debugger that generates HTML

[jasonhan3]

closes #714

Example:

PR: Add an Interactive Kirin IR Inspector

Summary

Adds a self-contained HTML inspector for Kirin IR. The HTML view makes IR easier
to explore without changing Method.print() or the textual printer.

What Changed

• Add kirin.visualize.to_html and kirin.visualize.write_html.
• Export kirin.ir_to_html and kirin.write_ir_html as public aliases.
• Add Method.visualize(path, *, analysis=None, title=None).
• Render SSA values as hoverable elements showing their type, producer, uses,
  hints, and optional analysis result.
• Render statements as hoverable elements showing their Python class, dialect,
  operation, operands, results, attributes, traits, regions, and source
  location/source snippet when available.
• Add an example and focused HTML-inspector tests.

Usage

Generate a file from a compiled kernel:

from pathlib import Path

from kirin.prelude import basic


@basic
def add_one(x: int) -> int:
    return x + 1


add_one.visualize(Path("add_one.ir.html"))

Open add_one.ir.html in a browser, or with the VS Code command
Kirin: Open IR Inspector.

In a Jupyter notebook, display the inspector in the output cell:

from IPython.display import HTML, display
from kirin import ir_to_html

display(HTML(ir_to_html(add_one)))

Pass an analysis frame or mapping to include a fact for each SSA value:

display(HTML(ir_to_html(add_one, analysis=analysis_results)))

Validation

• uv run pytest
• uv run ruff check src/kirin/visualize.py src/kirin/ir/method.py src/kirin/__init__.py test/visualize/test_html.py
• uv run pyright src/kirin/visualize.py src/kirin/ir/method.py

Scope

This does not alter kirin.print() and does not provide step-through or
breakpoint debugging. It establishes a reusable HTML visualization surface
that can be embedded in notebooks, opened in a browser, or hosted by an IDE.

[codecov]

Codecov Report

❌ Patch coverage is 91.25683% with 16 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/kirin/visualize.py	91.01%	16 Missing ⚠️

📢 Thoughts on this report? Let us know!

[github-actions]

☂️ Code Coverage

current status: ✅

Overall Coverage

Statements	Covered	Coverage	Threshold	Status
12060	10879	90%	0%	🟢

New Files

File	Coverage	Status
src/kirin/visualize.py	91%	🟢
TOTAL	91%	🟢

Modified Files

File	Coverage	Status
src/kirin/_init_.py	100%	🟢
src/kirin/ir/method.py	98%	🟢
TOTAL	99%	🟢

updated for commit: a39359c by action🐍

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://QuEraComputing.github.io/kirin/pr-preview/pr-715/
Built to branch gh-pages at 2026-08-29 22:24 UTC. Preview will be ready when the GitHub Pages deployment is complete.