structile 6.0.0__py3-none-any.whl

structile/__init__.py

@@ -0,0 +1,544 @@
+"""Display Python data through Structile, wherever you're running.
+
+    import structile as st
+    st.open({"a": 1, "b": [1, 2, 3]})
+    st.open("results.json")
+
+`open()` renders through whichever renderer is active — an inline
+Jupyter widget, a browser tab, a written HTML file, a terminal summary, or
+nothing at all — matplotlib-backend style (see `render.py`). See README.md
+for the full picture (renderers, install steps, supported types, current
+limitations).
+"""
+from __future__ import annotations
+
+from importlib import metadata
+import json
+import pathlib
+from typing import Any, Callable, Dict, Optional, Tuple, Union
+
+from ._log import logger as _logger
+from ._paths import (
+    InterpreterSource,
+    as_path_like as _as_path_like,
+    read_interpreter as _read_interpreter,
+    read_text as _read_text,
+    strict_json_loads as _strict_json_loads,
+)
+from .config import Options, get_option, options, options_from_dict, replace_options, reset_option, resolve_config, resolve_renderer, set_option, use
+from .convert import convert
+from .interpreters import (
+    CANONICAL_EXT_FOR_FORMAT as _CANONICAL_EXT_FOR_FORMAT,
+    InterpreterSpec,
+    MARKUP_FORMATS,
+    _normalize_ext,
+    get_registered_interpreter,
+    register_interpreter,
+    resolve_candidates as _resolve_interpreter_candidates,
+    unregister_interpreter,
+)
+from ._plugins import PluginRecord, load_plugins, plugins
+from .render import (
+    DiffRenderHandle,
+    Payload as _Payload,
+    RENDERERS,
+    RenderHandle,
+    detect_renderer as _detect_renderer,
+    render as _render,
+    render_diff as _render_diff,
+)
+from .serialize import normalize
+from .widget import (
+    StructileDiffWidget,
+    StructileWidget,
+)
+
+_VERSION_FILE = pathlib.Path(__file__).resolve().parent.parent / "VERSION"
+if _VERSION_FILE.is_file():
+    __version__ = _VERSION_FILE.read_text(encoding="utf-8").strip()
+else:
+    __version__ = metadata.version("structile")
+
+__all__ = [
+    "open",
+    "diff",
+    "convert",
+    "normalize",
+    "StructileWidget",
+    "StructileDiffWidget",
+    "RenderHandle",
+    "DiffRenderHandle",
+    "RENDERERS",
+    "Options",
+    "options",
+    "options_from_dict",
+    "set_option",
+    "get_option",
+    "reset_option",
+    "replace_options",
+    "use",
+    "register_interpreter",
+    "unregister_interpreter",
+    "get_registered_interpreter",
+    "InterpreterSource",
+    "load_plugins",
+    "plugins",
+    "PluginRecord",
+    "__version__",
+]
+
+
+def _load_path(path: Any) -> Tuple[Any, str, str, bool]:
+    """Returns `(data, name, raw_text, parsed_as_json)` — `raw_text` is the
+    file's literal, unmodified content; `parsed_as_json` tells the caller
+    whether `raw_text` itself IS a JSON document representing `data` (safe
+    to forward verbatim as source text) or whether `data` is really just
+    `raw_text` wrapped as a plain string (the "unrecognized extension falls
+    back to plain text" case below) — in which case `raw_text` is arbitrary
+    non-JSON content and must NOT be handed to the viewer as `format="json"`
+    source text (see `open()`'s own use of this)."""
+    p = pathlib.Path(path)
+    text = _read_text(p)
+    if p.suffix.lower() == ".json":
+        # strict_json_loads (not a bare json.loads): a NaN/Infinity/-Infinity
+        # literal anywhere in the document is something CPython's json
+        # module tolerates but structile.html's own JSON.parse-
+        # based parser does not — letting one through here would mean
+        # forwarding text below as trusted format="json" source that the
+        # viewer then fails to parse. Treating it as malformed (raising, same
+        # as any other invalid .json file) is consistent with this branch's
+        # existing "let a malformed .json file raise" rule below.
+        data = _strict_json_loads(text)  # let a malformed .json file raise, rather than silently showing raw text
+        parsed_as_json = True
+    else:
+        try:
+            data = _strict_json_loads(text)
+            parsed_as_json = True
+        except ValueError:
+            data = text
+            parsed_as_json = False
+    return data, p.stem, text, parsed_as_json
+
+
+def _is_markup_mode(ext: Optional[str], interpreter: Optional[InterpreterSpec], fmt: Optional[str]) -> bool:
+    """True when `obj`/a diff side is markup/interpreter mode rather than a
+    plain JSON/Python value: an explicit `interpreter=`, an explicit
+    `format=` other than "json"/"python", or a registered interpreter for
+    the inferred extension (so nothing registered + no `interpreter=` stays
+    plain-value mode)."""
+    if interpreter is not None or (fmt is not None and fmt not in ("json", "python")):
+        return True
+    return bool(ext) and get_registered_interpreter(ext) is not None
+
+
+def _resolve_markup_source(
+    obj: Any,
+    *,
+    source_path: Optional[pathlib.Path],
+    ext: Optional[str],
+    interpreter: Optional[InterpreterSpec],
+    format: Optional[str],
+    fallback_name: str,
+    allow_format_unknown: bool,
+    error_prefix: str,
+    bad_obj_message: str,
+    unknown_format_message: str,
+) -> _Payload:
+    """Resolve one markup/interpreter-mode source — `open()`'s own
+    `obj`, or one side of `diff()` (`_resolve_diff_side`, below) — into a
+    `Payload` (`config` unset; only `open()` has one to set, after
+    the call). Shared so "classify -> load text -> infer format -> resolve
+    interpreter candidate(s)" lives once instead of twice.
+    `allow_format_unknown` is the one real fork between the callers: only
+    `open()` lets an interpreter dict spanning several extensions
+    resolve its format client-side (a diff side must already be
+    classifiable on its own)."""
+    if source_path is not None:
+        text = _read_text(source_path)
+        registered = bool(ext) and get_registered_interpreter(ext) is not None
+        # ".ini" -> "ini" once something's actually attached to it — see
+        # _is_markup_mode above.
+        fmt = format or MARKUP_FORMATS.get(ext) or (ext.lstrip(".") if ext and (interpreter is not None or registered) else None)
+        inferred_name = source_path.stem
+    elif isinstance(obj, str):
+        text, fmt, inferred_name = obj, format, fallback_name
+    else:
+        raise TypeError(bad_obj_message)
+
+    if fmt:
+        candidates = _resolve_interpreter_candidates(interpreter, ext or _CANONICAL_EXT_FOR_FORMAT.get(fmt))
+        if not candidates:
+            raise ValueError(
+                f"{error_prefix}: no interpreter registered or provided for {fmt!r} data — pass interpreter=, "
+                "or call register_interpreter(ext, ...) once at import time"
+            )
+        # Every renderer (including widget) only ever forwards the
+        # interpreter source(s) on to be run client-side — none of them need
+        # Python to have actually RUN it, so no Node is needed here
+        # regardless of candidate count.
+        sources = [_read_interpreter(c) for c in candidates]
+        interpreter_source = sources[0] if len(sources) == 1 else sources
+        return _Payload(text=text, format=fmt, name=inferred_name, interpreter_source=interpreter_source)
+
+    if allow_format_unknown and isinstance(interpreter, dict) and interpreter and source_path is None:
+        # No format= and nothing to infer one from a path — build a
+        # {format: [sources...]} map for every entry in the dict and let the
+        # BROWSER itself figure out which one applies
+        # (tryInterpreterCandidatesAnyFormat in structile.html),
+        # instead of resolving it here. Doing this in Python would need
+        # Node.js just to decide which format applies — open() must
+        # never need Node for anything a browser can just as well decide for
+        # itself. A markup extension's format comes from MARKUP_FORMATS (its
+        # DOM mode); any other extension's format is just itself (".ini" ->
+        # "ini") — every entry is a candidate now, not just recognized-markup
+        # ones.
+        candidates_by_format: Dict[str, list] = {}
+        for ext_key in interpreter.keys():
+            ext_norm = _normalize_ext(ext_key)
+            fmt_for_ext = MARKUP_FORMATS.get(ext_norm) or ext_norm.lstrip(".")
+            cands = _resolve_interpreter_candidates(interpreter, ext_norm)
+            if cands:
+                candidates_by_format.setdefault(fmt_for_ext, []).extend(_read_interpreter(c) for c in cands)
+        if not candidates_by_format:
+            raise ValueError(f"{error_prefix}: interpreter dict has no usable entries")
+        return _Payload(text=text, format="", name=inferred_name, interpreter_candidates_by_format=candidates_by_format)
+
+    raise ValueError(unknown_format_message)
+
+
+def open(
+    obj: Any,
+    *,
+    name: Optional[str] = None,
+    height: int = 600,
+    config: Optional[Union[Options, Dict[str, Any]]] = None,
+    interpreter: Optional[InterpreterSpec] = None,
+    format: Optional[str] = None,
+    path: Optional[Union[str, pathlib.Path]] = None,
+    renderer: Optional[str] = None,
+    out: Optional[Union[str, pathlib.Path]] = None,
+    auto_open: bool = True,
+    default: Optional[Callable[[Any], Any]] = None,
+    **settings: Any,
+) -> RenderHandle:
+    """Display a Python value through the active renderer. Always returns a
+    `RenderHandle` (never `None`) with `.path`, `.value`, `.open()`,
+    `.to_html()`, `.save(path)`, and a one-line `repr()` — evaluate it as
+    the last expression in a Jupyter cell, or pass it to
+    `IPython.display.display`, and it renders itself richly there too.
+
+    See README.md ("Python / Jupyter (structile.open)") for examples and the
+    full picture — this is a parameter reference, not a tutorial. Shadows
+    the `open` builtin — always call this namespace-qualified
+    (`structile.open(...)`), never `from structile import open`.
+
+    obj: the value to display — any mix of dict/list/tuple/set/None/bool/
+        int (any size)/float/str/numpy scalar — or a `pathlib.Path`/`str`
+        naming an existing file to load it from (JSON, falling back to
+        plain text). When loaded from a path whose content IS valid JSON,
+        the file's own literal bytes (not a re-serialization) are what the
+        viewer's source pane shows/edits/saves — so original formatting
+        (whitespace, key order, ...) survives untouched until an edit
+        actually touches it. There's no such "original text" for an
+        in-memory `obj` (no path) or for a path that falls back to plain
+        text (below) — both show a freshly-serialized JSON view instead, as
+        they always have. A path whose extension is markup-like (`.xml`,
+        `.html`/`.htm` — see `interpreters.MARKUP_FORMATS`), or has an
+        interpreter attached to it (`interpreter=`, or something already
+        registered via `register_interpreter`), or `format=` set explicitly
+        to anything other than `"json"`/`"python"`, switches to interpreter
+        mode: `obj` (or a literal string, with `format=` then required) is
+        handed to an interpreter instead of being read as a Python value —
+        see `interpreter=` below. `.xml`/`.html` use the DOM-based
+        `interpretXML(xmlDocument)` contract; any other format (`.ini`,
+        `.toml`, ...) uses the raw-text `interpretText(text)` contract — see
+        interpreters/generic_xml.js vs interpreters/generic_ini.js.
+    name: display name. Defaults to the loaded file's stem, else "data".
+    height: iframe height in px (`widget` renderer only).
+    config: viewer settings for this call — an `Options` instance, or a
+        plain dict of the same keys (`config={"gap": 8, "forNull": "N/A"}`),
+        whichever's more convenient; a dict is just turned into an `Options`
+        internally (see `options_from_dict`).
+    **settings: individual viewer settings for this call — the numeric
+        layout knobs (`gap`, `n`, `m`, `N`, `M`, `nameMax`, `valMax`,
+        `headerLabelMax`, `detCols`, `detRows`, `dwellMs`, `kvRows`,
+        `kvCols`, `maxWidthFrac`), `theme`, the "Special values" display
+        overrides the viewer's Settings panel edits under that name —
+        `forNull`/`forEmpty` (strings shown in place of `None`/`""`) and
+        `values` (a `{exact_string: replacement}` table) — cosmetic only,
+        never changes the underlying data; and `linkOpen`/`linkClose`, the
+        viewer's cross-reference-value marker — a dict value/table cell
+        wrapped between them, verbatim (delimiters included), that names
+        another dict/table anywhere in the document becomes a clickable
+        link that jumps to it (see `Options`). `config=` and
+        `**settings` both take precedence over `structile.options` /
+        `set_option(...)`; anything left unset everywhere falls back to the
+        viewer's default. There's no Settings panel in embedded (widget)
+        mode, so this is the only way to reach these from Python there —
+        e.g. `structile.open(data, forNull="N/A")` to show `None` as `"N/A"`
+        everywhere it appears, including nested inside dicts/lists, or
+        `structile.open(data, linkOpen="<link.id", linkClose=">")` so a value
+        like `"<link.id.20>"` links to a same-named dict/table.
+    interpreter: a path to a `.js` interpreter script, raw JS source
+        (`interpretXML(xmlDocument)` + optional `serializeXML(value)` for
+        markup; `interpretText(text)` + optional `serializeText(value)` for
+        any other text format — see interpreters/generic_xml.js,
+        interpreters/html.js, interpreters/generic_ini.js), or an
+        `InterpreterSource` (source text supplied directly rather than read
+        from a path — what an installed plugin package hands
+        `register_interpreter`; see `structile.plugins()`); a list mixing
+        any of the above; or a dict keyed by file extension (`{".xml": [...],
+        ".html": [...]}`) — only the entry matching the actual file/format
+        is tried, never another extension's candidates (see
+        `resolve_candidates`). Multiple candidates are never disambiguated
+        in Python — the source(s) are forwarded as-is to whichever renderer
+        is active, which tries each one itself (`tryInterpreterCandidates`
+        in structile.html) and reports which one worked. This
+        needs no Node.js, for any renderer including `widget`. Not required
+        if something's already registered for the extension
+        (`register_interpreter`, set up once at import time) — this only
+        overrides that for one call.
+    format: `"xml"` | `"html"` | any other string (e.g. `"ini"`) —
+        required alongside `interpreter=`/a registered interpreter when
+        `obj` isn't a path (no extension to infer it from) — *unless*
+        `interpreter=` is a dict spanning more than one extension, in which
+        case omitting `format=` forwards every entry (each under its own
+        extension's format) to the renderer, which determines the format
+        itself the same no-Node way (`tryInterpreterCandidatesAnyFormat`) —
+        Python never has to run anything just to decide which format
+        applies, or which contract (DOM vs. raw-text) it uses. Any format
+        other than `"xml"`/`"html"` runs through the raw-text
+        `interpretText(text)` contract instead of DOM parsing.
+    path: save destination, overriding `obj`'s own source path (if any) —
+        `widget` renderer only (the other renderers never write back to a
+        source file; see the `browser`/`file`/`none`/`text` docs).
+    renderer: `"widget"` | `"browser"` | `"file"` | `"none"` | `"text"` —
+        overrides resolution for this call only. Otherwise resolved via
+        `STRUCTILE_RENDERER` -> `config`/`structile.options.renderer`
+        (`set_option`/`use`) -> auto-detect (see `render.detect_renderer`).
+    out: also write the standalone HTML snapshot here (any renderer).
+    auto_open: set `False` to suppress the `browser` renderer's automatic
+        `webbrowser.open()` (it still writes the file; call `.open()` later
+        to open it manually).
+    default: called on any value that isn't one of `obj`'s own supported
+        types (see above); its return value is normalized in its place,
+        same escape hatch as `json.dumps(..., default=...)` — e.g.
+        `default=str` displays an otherwise-unsupported object as whatever
+        `str()` shows for it, instead of raising `TypeError`. See
+        `structile.normalize`.
+    """
+    if isinstance(config, dict):
+        config = options_from_dict(config)
+    embed_config = resolve_config(settings, config)
+    config_json = json.dumps(embed_config) if embed_config is not None else "null"
+    resolved_renderer = resolve_renderer(renderer, config) or _detect_renderer()
+    save_path = pathlib.Path(path) if path is not None else None
+
+    source_path = _as_path_like(obj)
+    ext = source_path.suffix.lower() if source_path is not None else None
+    if _is_markup_mode(ext, interpreter, format):
+        payload = _resolve_markup_source(
+            obj,
+            source_path=source_path,
+            ext=ext,
+            interpreter=interpreter,
+            format=format,
+            fallback_name="data",
+            allow_format_unknown=True,
+            error_prefix="structile",
+            bad_obj_message=(
+                "structile: with interpreter=/format=/a registered extension, "
+                "obj must be a file path or a raw string"
+            ),
+            unknown_format_message=(
+                "structile: could not infer a format for this data; pass format=... "
+                '(e.g. format="xml", format="html", or a custom format like format="ini")'
+            ),
+        )
+        payload.name = name or payload.name
+        payload.config = embed_config
+        _logger.debug("structile: markup mode (%s)", payload.format)
+        widget = None
+        if resolved_renderer == "widget":
+            widget = StructileWidget(
+                raw_text=payload.text,
+                raw_format=payload.format or "",
+                interpreter_source=payload.interpreter_source or "",
+                interpreter_candidates_by_format=payload.interpreter_candidates_by_format or {},
+                data_name=payload.name,
+                height=height,
+                config_json=config_json,
+                value=payload.text,
+                source_path=source_path,
+                save_path=save_path,
+            )
+        # Markup mode's own "value" is just the raw text (nothing to parse
+        # in Python — see payload.text above).
+        return _render(payload, value=payload.text, renderer=resolved_renderer, widget=widget, out=out, auto_open=auto_open)
+
+    if source_path is not None:
+        data, inferred_name, raw_text, parsed_as_json = _load_path(source_path)
+    else:
+        # "" (not "data"): an in-memory value has no real file/save identity
+        # behind it, and the viewer's #fileNameLabel treats a falsy name as
+        # exactly that signal — showing the bare display name instead of a
+        # fabricated "name.json" that would misleadingly read as an actual
+        # loaded file (see updateFileNameLabel/hasRealFileName in
+        # structile.html). name= still wins below if the caller
+        # gave one explicitly.
+        data, inferred_name, raw_text, parsed_as_json = obj, "", None, False
+    normalized = normalize(data, default)
+    display_name = name or inferred_name
+    # source_code_view_claude.md Phase 6: when this was loaded from a real
+    # file that IS a JSON document, forward its literal bytes as the source
+    # text — preserving the file's own formatting (whitespace, key order,
+    # ...) for the viewer's source pane — instead of a re-serialization that
+    # was never what was actually on disk. No such "original text" exists
+    # for an in-memory value (raw_text is None) or for a path whose content
+    # isn't valid JSON (parsed_as_json is False — the historical "unrecognized
+    # extension falls back to plain text" case, where raw_text is arbitrary
+    # non-JSON content and would break the viewer if sent as format="json"
+    # source text) — both keep today's re-serialize-as-text behavior, pretty-
+    # printed (indent=2, matching the viewer's own JSON.stringify(v, null, 2)
+    # elsewhere) so the source pane never shows a single minified line.
+    text = raw_text if (raw_text is not None and parsed_as_json) else json.dumps(normalized, indent=2)
+    widget = None
+    if resolved_renderer == "widget":
+        widget = StructileWidget(
+            value_json=text,
+            data_name=display_name,
+            height=height,
+            config_json=config_json,
+            value=normalized,
+            source_path=source_path,
+            save_path=save_path,
+        )
+    payload = _Payload(text=text, format="json", name=display_name, config=embed_config)
+    return _render(payload, value=normalized, renderer=resolved_renderer, widget=widget, out=out, auto_open=auto_open)
+
+
+def _resolve_diff_side(
+    obj: Any,
+    *,
+    interpreter: Optional[InterpreterSpec],
+    fmt: Optional[str],
+    side_label: str,
+    default: Optional[Callable[[Any], Any]] = None,
+) -> _Payload:
+    """Resolve one side of a `diff()` call into a `Payload` — mirrors
+    `open()`'s own markup-mode branch via the shared
+    `_resolve_markup_source` helper, scoped to what a single diff side
+    needs: the format-unknown "dict spanning several extensions, let the
+    browser pick the format" case doesn't apply here, since each side must
+    already be classifiable (markup or plain value) before the two sides
+    can even be compared."""
+    source_path = _as_path_like(obj)
+    ext = source_path.suffix.lower() if source_path is not None else None
+    if _is_markup_mode(ext, interpreter, fmt):
+        return _resolve_markup_source(
+            obj,
+            source_path=source_path,
+            ext=ext,
+            interpreter=interpreter,
+            format=fmt,
+            fallback_name=side_label,
+            allow_format_unknown=False,
+            error_prefix=f"structile.diff ({side_label} side)",
+            bad_obj_message=(
+                f"structile.diff: with interpreter=/format= given for the {side_label} side, "
+                "it must be a file path or a raw string"
+            ),
+            unknown_format_message=(
+                f"structile.diff: could not infer a format for the {side_label} side; pass "
+                "format=... (or a (left, right) tuple if only one side is markup) for it"
+            ),
+        )
+
+    if source_path is not None:
+        data, inferred_name, _raw_text, _parsed_as_json = _load_path(source_path)
+    else:
+        data, inferred_name = obj, side_label
+    normalized = normalize(data, default)
+    return _Payload(text=json.dumps(normalized, indent=2), format="json", name=inferred_name)
+
+
+def diff(
+    left: Any,
+    right: Any,
+    *,
+    interpreter: Optional[Union[InterpreterSpec, Tuple[Optional[InterpreterSpec], Optional[InterpreterSpec]]]] = None,
+    format: Optional[Union[str, Tuple[Optional[str], Optional[str]]]] = None,
+    name: Optional[Tuple[Optional[str], Optional[str]]] = None,
+    view: str = "unified",
+    key_columns: Optional[list] = None,
+    height: int = 600,
+    renderer: Optional[str] = None,
+    out: Optional[Union[str, pathlib.Path]] = None,
+    auto_open: bool = True,
+    default: Optional[Union[Callable[[Any], Any], Tuple[Optional[Callable[[Any], Any]], Optional[Callable[[Any], Any]]]]] = None,
+) -> DiffRenderHandle:
+    """Display a two-sided diff of `left` vs `right` through the active
+    renderer. Always returns a `DiffRenderHandle` with `.path`,
+    `.left_payload`/`.right_payload`, `.left_value`/`.right_value`,
+    `.open()`, `.to_html()`, `.save(path)`.
+
+    See README.md ("Comparing two files (structile.diff)") for examples.
+    Deliberately narrower than `open()`: no per-side viewer
+    `config=`/`**settings`, and the diff graph itself is always read-only
+    for every renderer (including `widget`) — only each side's own source
+    pane can be independently edited/saved (see `.left_value`/
+    `.right_value`, which read through to the live `StructileDiffWidget`
+    for the `widget` renderer, same as `RenderHandle.value` does for
+    `open()`).
+
+    left, right: each independently accepts anything `open()`'s
+        `obj` does — a Python value, a path, or (with `interpreter=`/
+        `format=`) a raw XML string.
+    interpreter, format: a single value applies to BOTH sides (the common
+        case: two files in the same format/schema); a `(left, right)`
+        2-tuple gives each side its own — this is what lets `left` and
+        `right` be two genuinely different, mutually-incompatible XML
+        schemas, each with its own interpreter. See `open()`'s
+        `interpreter=`/`format=` docs for what a single value can be.
+    name: `(left_name, right_name)` — defaults to each side's own inferred
+        name (its file stem, or "left"/"right" for a raw string/value).
+    view: `"unified"` | `"split"`.
+    key_columns: table key-column overrides — same shape the standalone
+        viewer's own diff header accepts.
+    height: iframe height in px (`widget` renderer only).
+    renderer, out, auto_open: same as `open()`.
+    default: same escape hatch as `open()`'s `default=`, for
+        whichever side(s) are plain Python values (a markup/interpreter-mode
+        side never reaches `normalize()`, so this has no effect there) — a
+        single value applies to both sides; a `(left, right)` 2-tuple gives
+        each side its own, same convention as `interpreter=`/`format=`.
+    """
+    resolved_renderer = resolve_renderer(renderer, None) or _detect_renderer()
+    left_interp, right_interp = interpreter if isinstance(interpreter, tuple) else (interpreter, interpreter)
+    left_fmt, right_fmt = format if isinstance(format, tuple) else (format, format)
+    left_name, right_name = name if name is not None else (None, None)
+    left_default, right_default = default if isinstance(default, tuple) else (default, default)
+
+    left_payload = _resolve_diff_side(left, interpreter=left_interp, fmt=left_fmt, side_label="left", default=left_default)
+    right_payload = _resolve_diff_side(right, interpreter=right_interp, fmt=right_fmt, side_label="right", default=right_default)
+    if left_name:
+        left_payload.name = left_name
+    if right_name:
+        right_payload.name = right_name
+
+    widget = None
+    if resolved_renderer == "widget":
+        widget = StructileDiffWidget(
+            left=left_payload, right=right_payload, view=view, key_columns=key_columns, height=height
+        )
+
+    return _render_diff(
+        left_payload,
+        right_payload,
+        renderer=resolved_renderer,
+        view=view,
+        key_columns=key_columns,
+        widget=widget,
+        out=out,
+        auto_open=auto_open,
+    )

structile/__main__.py

@@ -0,0 +1,57 @@
+"""`python -m structile data.json [--interpreter x.js] [--renderer ...] [--out f.html]`
+
+A thin CLI over `open()` — same renderer resolution/auto-detect as
+calling it from a script (see render.py), just from a terminal instead.
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import Optional, Sequence
+
+from . import __version__
+from . import open as _open
+from . import plugins as _plugins
+from .render import RENDERERS
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    parser = argparse.ArgumentParser(prog="python -m structile", description="View a JSON / Python-repr / XML / HTML file with Structile.")
+    parser.add_argument("path", nargs="?", help="file to view (.json, .py, .xml, .html/.htm)")
+    parser.add_argument("--interpreter", metavar="FILE", help="a .js interpreter script (required for .xml/.html)")
+    parser.add_argument("--renderer", choices=RENDERERS, help="override renderer auto-detection")
+    parser.add_argument("--out", metavar="FILE", help="also write the standalone HTML snapshot here")
+    parser.add_argument("--no-open", action="store_true", help="don't open a browser tab (browser renderer only)")
+    parser.add_argument(
+        "--plugins",
+        action="store_true",
+        help="list installed structile.interpreters entry-point plugins (including any that failed to load) and exit",
+    )
+    parser.add_argument("--version", action="version", version=f"structile {__version__}")
+    args = parser.parse_args(argv)
+
+    if args.plugins:
+        records = _plugins()
+        if not records:
+            print("no structile.interpreters plugins found")
+        for record in records:
+            if not record.success:
+                print(f"{record.entry_point} ({record.distribution} {record.version}): FAILED — {record.error}")
+                continue
+            exts = ", ".join(record.extensions) if record.extensions else "(no extensions registered)"
+            print(f"{record.entry_point} ({record.distribution} {record.version}): {exts}")
+        return 0
+
+    if not args.path:
+        parser.error("the following arguments are required: path")
+
+    kwargs = dict(renderer=args.renderer, out=args.out, auto_open=not args.no_open)
+    if args.interpreter:
+        kwargs["interpreter"] = args.interpreter
+    handle = _open(args.path, **kwargs)
+    print(repr(handle))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())