structile 6.0.0__py3-none-any.whl

structile/render.py

@@ -0,0 +1,535 @@
+"""The renderer layer — matplotlib-backend style: where an `open()`
+call actually shows up (an inline widget, a browser tab, a written file, a
+terminal summary, or nowhere) is decided once, here, rather than being
+hardcoded to "inline Jupyter widget" the way the original single-path
+version of this package was.
+
+Every renderer produces the same thing: a `RenderHandle` — never `None`,
+never the raw ipywidgets object — so callers always have `.path`, `.value`,
+`.open()`, `.to_html()`, `.save(path)` available regardless of which
+renderer actually ran. `.to_html()` (and everything built on it: `.open()`,
+`.save()`, the `out=` kwarg) works the same way for every renderer, because
+it doesn't depend on which one was picked — it always rebuilds the
+STANDALONE viewer (settings bar, Phase A editing, undo/redo, client-side
+Save) as one self-contained HTML file, by reusing structile.html
+verbatim and injecting a small `window.__STRUCTILE_SNAPSHOT__` bootstrap before its
+main <script> tag (see applyInitialPayload in structile.html) — the
+exact same {text, format, name, interpreterSource?, config?} shape the
+embedded-mode protocol already uses, just consumed without ever calling
+enterEmbedMode(), so none of the standalone chrome gets hidden.
+"""
+from __future__ import annotations
+
+import html as _html
+import json
+import os
+import sys
+import tempfile
+import uuid
+import webbrowser
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional, Union
+
+from ._log import logger
+from ._paths import find_viewer_html
+
+RENDERERS = ("widget", "browser", "file", "none", "text")
+
+# The one place in structile.html this module depends on the exact
+# shape of: the main <script> tag, identified by the "use strict" that
+# immediately follows it on the next line (the bare substring "<script>"
+# alone also appears inside a couple of comments elsewhere in the file — see
+# AGENTS.md's note on that CSP-injection lesson from the VS Code extension).
+_SNAPSHOT_ANCHOR = '\n<script>\n"use strict";'
+
+_temp_dir: Optional[str] = None
+
+
+def _session_temp_dir() -> str:
+    """A stable per-process temp directory for generated snapshot HTML —
+    created lazily, on first use, and never cleaned up: the whole point of
+    `browser`/`file` rendering is that the file outlives this call (the
+    browser may not even have finished loading it by the time the process
+    exits), so auto-deleting it would be actively hostile."""
+    global _temp_dir
+    if _temp_dir is None:
+        _temp_dir = tempfile.mkdtemp(prefix="structile_")
+    return _temp_dir
+
+
+def _write_session_temp(html_text: str) -> "os.PathLike":
+    import pathlib
+
+    p = pathlib.Path(_session_temp_dir()) / (uuid.uuid4().hex[:8] + ".html")
+    p.write_text(html_text, encoding="utf-8")
+    logger.debug("structile: wrote standalone HTML to session temp file %s", p)
+    return p
+
+
+# ---- auto-detection ----------------------------------------------------
+def _in_rich_ipython_kernel() -> bool:
+    try:
+        from IPython import get_ipython
+    except ImportError:
+        return False
+    ip = get_ipython()
+    if ip is None:
+        return False
+    if type(ip).__name__ == "ZMQInteractiveShell":  # Jupyter classic/lab, VS Code notebooks
+        return True
+    return "google.colab" in sys.modules  # Colab's own shell class isn't ZMQInteractiveShell, but is just as rich
+
+
+def _headless() -> bool:
+    if os.environ.get("SSH_CONNECTION"):
+        return True
+    if sys.platform.startswith("linux") and not (os.environ.get("DISPLAY") or os.environ.get("WAYLAND_DISPLAY")):
+        return True
+    try:
+        webbrowser.get()
+    except webbrowser.Error:
+        return True
+    return False
+
+
+def detect_renderer() -> str:
+    """Auto-detect which renderer to use when nothing resolved one
+    explicitly (see `config.resolve_renderer`)."""
+    if os.environ.get("CI") or os.environ.get("PYTEST_CURRENT_TEST"):
+        logger.debug("structile: CI/PYTEST_CURRENT_TEST set, auto-detected renderer=none")
+        return "none"  # stray debug calls in a test suite should never spawn browser tabs
+    if _in_rich_ipython_kernel():
+        logger.debug("structile: rich IPython kernel detected, auto-detected renderer=widget")
+        return "widget"
+    resolved = "file" if _headless() else "browser"
+    logger.debug("structile: auto-detected renderer=%r (headless=%s)", resolved, resolved == "file")
+    return resolved
+
+
+# ---- payload / standalone HTML ------------------------------------------
+@dataclass
+class Payload:
+    """Everything needed to (re)build the standalone HTML for a render, or
+    to describe it in a repr/text summary — independent of which renderer
+    actually ran."""
+
+    text: str
+    format: str  # "json" | "python" | "xml" | "html" | any other interpreter format | "" (format unknown — see interpreter_candidates_by_format)
+    name: str
+    # A single interpreter source, or a list of candidates for the browser
+    # to try itself (tryInterpreterCandidates in structile.html) —
+    # see open()'s markup-mode branch for when a list is built.
+    interpreter_source: Optional[Union[str, List[str]]] = None
+    # Set instead of interpreter_source (format left "") when the format
+    # itself isn't known ahead of time — a dict of {"xml": [...], "ini":
+    # [...], ...} (any mix of markup and other formats), tried by the
+    # browser itself via tryInterpreterCandidatesAnyFormat, which also
+    # determines the winning format. Deliberately never resolved in
+    # Python: doing so would need Node.js just to decide which format
+    # applies, and open() must not depend on Node for anything a
+    # browser can decide for itself.
+    interpreter_candidates_by_format: Optional[Dict[str, List[str]]] = None
+    config: Optional[Dict[str, Any]] = None
+
+    def to_snapshot_dict(self) -> Dict[str, Any]:
+        d: Dict[str, Any] = {"text": self.text, "format": self.format, "name": self.name}
+        if self.interpreter_source:
+            d["interpreterSource"] = self.interpreter_source
+        if self.interpreter_candidates_by_format:
+            d["interpreterCandidatesByFormat"] = self.interpreter_candidates_by_format
+        if self.config is not None:
+            d["config"] = self.config
+        return d
+
+
+def _inject_snapshot(snapshot: Dict[str, Any]) -> str:
+    """Splice an arbitrary `window.__STRUCTILE_SNAPSHOT__` payload into a fresh
+    read of structile.html, right before its main <script> tag.
+    Shared by `build_standalone_html` (single-value) and
+    `build_standalone_diff_html` (two-value, below) — both just build a
+    JSON-safe dict in the shape `applyInitialPayload`/`loadDiffPayload`
+    already know how to consume and hand it here."""
+    viewer_html = find_viewer_html().read_text(encoding="utf-8")
+    idx = viewer_html.find(_SNAPSHOT_ANCHOR)
+    if idx == -1:
+        raise RuntimeError(
+            "structile: could not find structile.html's main <script> tag "
+            "to inject the snapshot before — has the viewer's structure changed?"
+        )
+    # `<` -> <, same escaping the VS Code extension's jsonForScript uses,
+    # so a "</script"-shaped substring anywhere in the data can't break out
+    # of this <script> block.
+    snapshot_json = json.dumps(snapshot).replace("<", "\\u003c")
+    snippet = "\n<script>\nwindow.__STRUCTILE_SNAPSHOT__ = " + snapshot_json + ";\n</script>\n"
+    return viewer_html[:idx] + snippet + viewer_html[idx:]
+
+
+def build_standalone_html(payload: Payload) -> str:
+    return _inject_snapshot(payload.to_snapshot_dict())
+
+
+def build_standalone_diff_html(
+    left: Payload,
+    right: Payload,
+    *,
+    view: str = "unified",
+    key_columns: Optional[list] = None,
+) -> str:
+    """The diff-mode counterpart to `build_standalone_html` — a
+    `mode: "diff"` snapshot with both sides, per diff_plan.md's "Payload And
+    Protocol Shape". This is deliberately narrow: just enough to build the
+    standalone diff HTML from two already-prepared `Payload`s (used by
+    `scripts/build_samples.py` to regenerate `samples/diff_demo*.html`
+    without ever hand-copying viewer code into them) — not the full
+    `structile.diff()` Python entry point (renderer resolution, a
+    `DiffRenderHandle`, `key_columns=` auto-detection, ...), which is
+    diff_plan.md Phase 7 and not implemented yet.
+
+    `left`/`right` can be different formats and each carries its own
+    `interpreter_source` independently (structile.html's
+    `leftInterpreterSource`/`rightInterpreterSource` — see
+    `loadDiffPayload`) — there is no requirement that they match, or that
+    only one side is markup.
+    """
+    snapshot: Dict[str, Any] = {
+        "mode": "diff",
+        "left": {"text": left.text, "format": left.format, "name": left.name},
+        "right": {"text": right.text, "format": right.format, "name": right.name},
+    }
+    if left.interpreter_source:
+        snapshot["leftInterpreterSource"] = left.interpreter_source
+    if right.interpreter_source:
+        snapshot["rightInterpreterSource"] = right.interpreter_source
+    if left.config is not None:
+        snapshot["config"] = left.config
+    if key_columns:
+        snapshot["keyColumns"] = list(key_columns)
+    if view and view != "unified":
+        snapshot["diff"] = {"view": view}
+    return _inject_snapshot(snapshot)
+
+
+def _describe_value(value: Any, fmt: str) -> str:
+    if fmt and fmt not in ("json", "python"):
+        return f"{fmt}, {len(value)} chars"
+    if isinstance(value, dict):
+        return f"dict, {len(value)} key{'' if len(value) == 1 else 's'}"
+    if isinstance(value, (list, tuple, set, frozenset)):
+        return f"{type(value).__name__}, {len(value)} item{'' if len(value) == 1 else 's'}"
+    if isinstance(value, str):
+        return f"str, {len(value)} chars"
+    return type(value).__name__
+
+
+def _text_summary(value: Any, name: str, fmt: str, *, max_items: int = 12, max_depth: int = 2) -> str:
+    """A compact terminal summary — type counts, top-level keys, a
+    truncated tree. Deliberately NOT a text rendering of the viewer's own 2D
+    packed layout (that's a browser-only concern); this is closer to what
+    `du -h --max-depth` or `df.info()` gives you: enough to sanity-check
+    what would be shown, not a substitute for actually looking at it."""
+    lines = [f"structile: {name or 'data'} ({_describe_value(value, fmt)})"]
+    if fmt and fmt not in ("json", "python"):
+        snippet = value.strip().replace("\n", " ")
+        lines.append("  " + (snippet[:200] + "..." if len(snippet) > 200 else snippet))
+        return "\n".join(lines)
+
+    def scalar(v: Any) -> str:
+        return repr(v) if not isinstance(v, (dict, list, tuple, set, frozenset)) else _describe_value(v, "json")
+
+    def walk(v: Any, depth: int, prefix: str) -> None:
+        if depth > max_depth:
+            return
+        if isinstance(v, dict):
+            keys = list(v.keys())
+            for k in keys[:max_items]:
+                child = v[k]
+                lines.append(f"{prefix}{k}: {scalar(child)}")
+                if isinstance(child, (dict, list, tuple, set, frozenset)):
+                    walk(child, depth + 1, prefix + "  ")
+            if len(keys) > max_items:
+                lines.append(f"{prefix}... (+{len(keys) - max_items} more keys)")
+        elif isinstance(v, (list, tuple, set, frozenset)):
+            items = list(v)
+            for i, child in enumerate(items[:max_items]):
+                lines.append(f"{prefix}[{i}]: {scalar(child)}")
+                if isinstance(child, (dict, list, tuple, set, frozenset)):
+                    walk(child, depth + 1, prefix + "  ")
+            if len(items) > max_items:
+                lines.append(f"{prefix}... (+{len(items) - max_items} more items)")
+
+    walk(value, 0, "  ")
+    return "\n".join(lines)
+
+
+# ---- the handle ----------------------------------------------------------
+class _RenderHandleBase:
+    """Shared `.path`/HTML-caching/save/open/repr plumbing for `RenderHandle`
+    and `DiffRenderHandle` — every renderer path funnels through the same
+    "lazily build the standalone HTML once, then write-or-open it" sequence
+    regardless of whether there's one document or two; only the HTML-
+    building itself and the live-value/repr semantics genuinely differ (see
+    each subclass's `_build_html`/`__repr__`/`.value`-or-`.left_value`).
+    `_log_prefix` is the one piece of per-subclass text every log line below
+    needs ("structile" vs "structile.diff")."""
+
+    _log_prefix = "structile"
+
+    def __init__(self) -> None:
+        self.path: Optional["os.PathLike"] = None
+        self._html: Optional[str] = None
+
+    def _build_html(self) -> str:
+        raise NotImplementedError
+
+    def to_html(self) -> str:
+        """The standalone viewer HTML for this render (settings bar, Phase
+        A editing, undo/redo, client-side Save) — built once, cached."""
+        if self._html is None:
+            self._html = self._build_html()
+        return self._html
+
+    def save(self, path) -> "os.PathLike":
+        """Write the standalone HTML to `path` (any renderer). Returns
+        `path` as a `pathlib.Path`; also becomes `.path` if nothing had been
+        written yet."""
+        import pathlib
+
+        p = pathlib.Path(path)
+        p.write_text(self.to_html(), encoding="utf-8")
+        logger.info("%s: wrote standalone HTML to %s", self._log_prefix, p)
+        if self.path is None:
+            self.path = p
+        return p
+
+    def open(self) -> "os.PathLike":
+        """Open the standalone HTML in a browser tab, generating it into
+        the session temp dir first if nothing's been written yet."""
+        if self.path is None:
+            self.path = _write_session_temp(self.to_html())
+        logger.info("%s: opening %s in a browser tab", self._log_prefix, self.path)
+        webbrowser.open(self.path.resolve().as_uri())
+        return self.path
+
+    def _repr_mimebundle_(self, include=None, exclude=None):
+        widget = getattr(self, "widget", None)
+        if widget is not None and hasattr(widget, "_repr_mimebundle_"):
+            return widget._repr_mimebundle_(include=include, exclude=exclude)
+        return {"text/plain": repr(self), "text/html": self._repr_html_()}
+
+    def _repr_html_(self) -> str:
+        text = _html.escape(repr(self))
+        if self.path is not None:
+            href = _html.escape(self.path.resolve().as_uri())
+            return f'<pre style="margin:0">{text}</pre><a href="{href}">{href}</a>'
+        return f'<pre style="margin:0">{text}</pre>'
+
+
+class RenderHandle(_RenderHandleBase):
+    """What every `open()` call returns, regardless of renderer.
+
+    `.value` is the displayed value (JSON-safe data, or raw XML text
+    when an `interpreter=` was used) — for the `widget` renderer this stays
+    live, updated on every Save (same as `StructileWidget.value` always
+    was); for every other renderer it's a static snapshot of what was
+    rendered, since there's no channel back from a plain browser tab/file to
+    Python. `.widget` is the underlying `StructileWidget` for the `widget`
+    renderer, `None` otherwise — an escape hatch for anywidget-specific
+    features (`.dirty`, `.dirty_count`, `.on_msg`, ...) this handle doesn't
+    itself proxy.
+    """
+
+    _log_prefix = "structile"
+
+    def __init__(self, *, renderer: str, payload: Payload, value: Any, widget: Any = None):
+        super().__init__()
+        self.renderer = renderer
+        self._value = value
+        self.widget = widget
+        self._payload = payload
+
+    @property
+    def value(self) -> Any:
+        # Reads through to the live widget for the `widget` renderer, so a
+        # save in the browser (which updates StructileWidget.value — see
+        # widget.py's _handle_save) is visible here immediately, with no
+        # separate copy of this handle's own to fall out of sync. Every
+        # other renderer has no such live source, so it falls back to the
+        # snapshot captured at render() time.
+        if self.widget is not None:
+            return self.widget.value
+        return self._value
+
+    @value.setter
+    def value(self, new_value: Any) -> None:
+        self._value = new_value
+
+    def _build_html(self) -> str:
+        return build_standalone_html(self._payload)
+
+    def set_value(self, obj: Any, *, name: Optional[str] = None) -> None:
+        """Replace the displayed value — only meaningful for the `widget`
+        renderer (every other renderer is a static, already-written
+        artifact)."""
+        if self.widget is None:
+            raise RuntimeError(
+                f"structile: set_value() needs the widget renderer (this call used renderer={self.renderer!r})"
+            )
+        self.widget.set_value(obj, name=name)  # self.value reads through to this
+
+    def __repr__(self) -> str:
+        desc = _describe_value(self.value, self._payload.format)
+        return f"<structile: {desc} -> {self.path}>" if self.path else f"<structile: {desc}>"
+
+
+class DiffRenderHandle(_RenderHandleBase):
+    """Returned by `structile.diff()` — the two-sided counterpart to
+    `RenderHandle`, deliberately narrow: the diff GRAPH is always read-only
+    (there's no single `.value` the way a plain document has one — see
+    `.left_payload`/`.right_payload` for the static snapshot each side
+    started from), but for the `widget` renderer, `.left_value`/
+    `.right_value` read through to the live `StructileDiffWidget` the same
+    way `RenderHandle.value` reads through to `StructileWidget` — each
+    side's own source pane is independently editable/saveable in embedded
+    diff mode (structile.html's `performDiffSideSave`), even though
+    the graph itself never is."""
+
+    _log_prefix = "structile.diff"
+
+    def __init__(
+        self,
+        *,
+        left: Payload,
+        right: Payload,
+        view: str = "unified",
+        key_columns: Optional[list] = None,
+        widget: Any = None,
+    ):
+        super().__init__()
+        self.left_payload = left
+        self.right_payload = right
+        self.view = view
+        self.key_columns = key_columns
+        self.widget = widget
+
+    @property
+    def left_value(self) -> Any:
+        return self.widget.left_value if self.widget is not None else None
+
+    @property
+    def right_value(self) -> Any:
+        return self.widget.right_value if self.widget is not None else None
+
+    def _build_html(self) -> str:
+        return build_standalone_diff_html(
+            self.left_payload, self.right_payload, view=self.view, key_columns=self.key_columns
+        )
+
+    def __repr__(self) -> str:
+        desc = f"{self.left_payload.name} vs {self.right_payload.name}"
+        return f"<structile diff: {desc} -> {self.path}>" if self.path else f"<structile diff: {desc}>"
+
+
+def _resolve_and_validate_renderer(explicit: Optional[str], *, log_prefix: str) -> str:
+    resolved = explicit or detect_renderer()
+    if resolved not in RENDERERS:
+        raise ValueError(f"{log_prefix}: unknown renderer {resolved!r} (expected one of {RENDERERS!r})")
+    return resolved
+
+
+def _write_or_open_standalone(handle: _RenderHandleBase, resolved: str, auto_open: bool) -> None:
+    """The `browser`/`file` half of `render()`/`render_diff()`'s dispatch —
+    identical for both (a `RenderHandle` and a `DiffRenderHandle` both know
+    how to lazily build+cache their own HTML via `to_html()`), so it's
+    shared rather than duplicated per caller. `widget`/`text`/`none` each
+    need caller-specific handling (a live widget, a value- or two-value-
+    shaped text summary, or nothing) and stay inline in each dispatcher."""
+    log_prefix = handle._log_prefix
+    if resolved == "browser":
+        if handle.path is None:
+            handle.path = _write_session_temp(handle.to_html())
+        if auto_open:
+            logger.info("%s: opening %s in a browser tab", log_prefix, handle.path)
+            webbrowser.open(handle.path.resolve().as_uri())
+        else:
+            logger.debug("%s: auto_open=False, wrote %s without opening it", log_prefix, handle.path)
+    elif resolved == "file":
+        if handle.path is None:
+            handle.path = _write_session_temp(handle.to_html())
+        logger.info("%s: wrote %s", log_prefix, handle.path)
+
+
+def render(
+    payload: Payload,
+    *,
+    value: Any,
+    renderer: Optional[str],
+    widget: Any = None,
+    out=None,
+    auto_open: bool = True,
+) -> RenderHandle:
+    """Dispatch a prepared `Payload` through the resolved renderer, always
+    returning a `RenderHandle`."""
+    resolved = _resolve_and_validate_renderer(renderer, log_prefix="structile")
+    logger.debug("structile: rendering %r (%s) via renderer=%r", payload.name, payload.format, resolved)
+    handle = RenderHandle(renderer=resolved, payload=payload, value=value, widget=widget if resolved == "widget" else None)
+
+    if out is not None:
+        handle.save(out)
+
+    # "widget": the widget itself is what actually renders; see
+    # _repr_mimebundle_. "none": render nothing beyond an explicit out=
+    # above.
+    _write_or_open_standalone(handle, resolved, auto_open)
+    if resolved == "text":
+        print(_text_summary(value, payload.name, payload.format))
+
+    return handle
+
+
+def _describe_payload_for_text(payload: Payload) -> str:
+    """`_describe_value`, but for a `Payload` that might not have had its
+    text parsed back into a Python value yet (`diff()` never parses markup
+    text in Python — that's the browser's job) — falls back to a raw
+    char-count description for xml/html, same as `_text_summary` does."""
+    if payload.format and payload.format not in ("json", "python"):
+        return f"{payload.format}, {len(payload.text)} chars"
+    try:
+        value = json.loads(payload.text)
+    except (ValueError, TypeError):
+        return f"{payload.format}, {len(payload.text)} chars"
+    return _describe_value(value, payload.format)
+
+
+def render_diff(
+    left: Payload,
+    right: Payload,
+    *,
+    renderer: Optional[str],
+    view: str = "unified",
+    key_columns: Optional[list] = None,
+    widget: Any = None,
+    out=None,
+    auto_open: bool = True,
+) -> DiffRenderHandle:
+    """The `structile.diff()` counterpart to `render()` — dispatches a
+    prepared pair of `Payload`s through the resolved renderer, always
+    returning a `DiffRenderHandle`. `widget` (a `StructileDiffWidget`,
+    built by `diff()` itself — mirrors `render()`'s own `widget` param) is
+    only meaningful when `renderer == "widget"`."""
+    resolved = _resolve_and_validate_renderer(renderer, log_prefix="structile.diff")
+    logger.debug("structile.diff: rendering %r vs %r via renderer=%r", left.name, right.name, resolved)
+    handle = DiffRenderHandle(
+        left=left, right=right, view=view, key_columns=key_columns, widget=widget if resolved == "widget" else None
+    )
+
+    if out is not None:
+        handle.save(out)
+
+    # "widget": the widget itself is what actually renders; see
+    # _repr_mimebundle_. "none": render nothing beyond an explicit out=
+    # above.
+    _write_or_open_standalone(handle, resolved, auto_open)
+    if resolved == "text":
+        print(f"structile diff: {left.name} ({_describe_payload_for_text(left)}) vs {right.name} ({_describe_payload_for_text(right)})")
+
+    return handle

structile/serialize.py

@@ -0,0 +1,88 @@
+"""Convert Python values into the JSON-safe form structile.html expects.
+
+structile.html keeps integers outside JavaScript's safe range
+(|v| >= 2**53) exact by re-scanning the *text* of a JSON document for bare
+integer literals as it parses (see jsonParsePreserveBigInt in
+structile.html) and reviving them as BigInt. json.dumps already
+emits Python's arbitrary-precision int as a bare numeric literal — exactly
+the shape that scan is built to catch — so this module needs no marker of
+its own for big integers; it only has to avoid the JSON-illegal shapes
+(non-finite floats, non-string dict keys, unsupported types) that would
+stop the text from parsing as JSON at all.
+"""
+from __future__ import annotations
+
+import math
+import warnings
+from typing import Any, Callable, Optional
+
+try:
+    import numpy as _np
+except ImportError:  # numpy is optional
+    _np = None
+
+_SCALAR_KEY_TYPES = (str, int, float, bool, type(None))
+
+
+def normalize(value: Any, default: Optional[Callable[[Any], Any]] = None) -> Any:
+    """Recursively convert a Python value into a JSON-safe structure.
+
+    Supported inputs: None, bool, int (any size), float, str, dict, list,
+    tuple, set, frozenset, and numpy scalars (if numpy is installed). Any
+    other type is passed to `default` (if given) and its return value
+    normalized in its place — same escape hatch as `json.dumps(...,
+    default=...)`, so e.g. `default=str` turns an otherwise-unsupported
+    object into whatever `str()` shows for it, instead of raising.
+    `default` can itself raise (or simply not be given) to keep today's
+    behavior for anything it doesn't recognize. Raises TypeError for
+    anything neither this nor `default` handles.
+    """
+    if _np is not None and isinstance(value, _np.generic):
+        return normalize(value.item(), default)
+    if value is None or isinstance(value, bool):
+        return value
+    if isinstance(value, int):
+        return value
+    if isinstance(value, float):
+        return _normalize_float(value)
+    if isinstance(value, str):
+        return value
+    if isinstance(value, dict):
+        return {_normalize_key(k): normalize(v, default) for k, v in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [normalize(v, default) for v in value]
+    if isinstance(value, (set, frozenset)):
+        try:
+            items = sorted(value)
+        except TypeError:
+            items = list(value)  # unorderable elements — fall back to iteration order
+        return [normalize(v, default) for v in items]
+    if default is not None:
+        return normalize(default(value), default)
+    raise TypeError(
+        f"structile: don't know how to display a value of type {type(value).__name__!r} "
+        "(supported: None, bool, int, float, str, dict, list, tuple, set, "
+        "frozenset, and numpy scalars)"
+    )
+
+
+def _normalize_key(key: Any) -> Any:
+    """JSON object keys are always strings; json.dumps already stringifies
+    str/int/float/bool/None keys itself (exactly, via str() — no precision
+    loss even for a huge int key), so only genuinely non-scalar keys (e.g.
+    a tuple) need converting here."""
+    if _np is not None and isinstance(key, _np.generic):
+        return _normalize_key(key.item())
+    if isinstance(key, _SCALAR_KEY_TYPES):
+        return key
+    return str(key)
+
+
+def _normalize_float(value: float) -> Any:
+    if math.isfinite(value):
+        return value
+    warnings.warn(
+        f"structile: {value!r} has no JSON representation; showing null instead",
+        stacklevel=3,
+    )
+    return None