structile 6.0.0__py3-none-any.whl

structile/config.py

@@ -0,0 +1,272 @@
+"""Configuration for `open()`, mirroring the viewer's own settings.
+
+Three ways to set an option, in increasing precedence:
+
+    structile.set_option("theme", "dark")     # module-level default
+    structile.options.gap = 8                 # same, attribute style
+    structile.open(data, gap=8, theme="dark") # per-call override
+
+An unset option (module default `None`, no per-call override) is simply
+omitted from the config handed to the viewer, so it falls back to the
+viewer's own built-in default (see SETTINGS_SCHEMA in
+structile.html) rather than to some second copy of that default
+kept here.
+
+`_OPTION_TYPES` mirrors structile.html's SETTINGS_SCHEMA (the
+numeric layout knobs) plus `theme`, which the viewer handles separately
+(see applySettingsFile's `payload.theme` handling) since it's a
+documentElement attribute, not a layout setting; `forNull`/`forEmpty`/
+`values`, the viewer's "Special values" display overrides (renderMap in
+structile.html — cosmetic only, never changes the underlying
+data); `linkOpen`/`linkClose`, the viewer's cross-reference-value marker
+(linkSettings in structile.html — a dict value/table cell wrapped
+between them that names another dict/table in the document becomes a
+clickable link that jumps to it; unlike forNull/forEmpty/values this one
+IS interactive, not purely cosmetic, but travels the same way); and
+`renderer`, which never reaches the viewer at all — it only
+picks which renderer (see render.py) `open()` dispatches to on the
+Python side, matplotlib-backend style (see `resolve_renderer`/`use`).
+
+`config=` also accepts a plain dict instead of an `Options` instance —
+`structile.open(data, config={"forNull": "N/A"})` — see `options_from_dict`,
+used internally by `open()` to coerce one before it ever reaches
+`resolve_config`/`resolve_renderer` (which still only accept `Options`).
+"""
+from __future__ import annotations
+
+import os
+from typing import Any, Dict, Optional
+
+from ._log import logger
+
+_OPTION_TYPES: Dict[str, type] = {
+    "nameMax": int,
+    "valMax": int,
+    "headerLabelMax": int,
+    "n": int,
+    "m": int,
+    "N": int,
+    "M": int,
+    "detCols": int,
+    "detRows": int,
+    "dwellMs": int,
+    "sourceAutoRenderMs": int,
+    "gap": int,
+    "kvRows": int,
+    "kvCols": int,
+    "maxWidthFrac": float,
+    "theme": str,
+    "renderer": str,
+    "forNull": str,
+    "forEmpty": str,
+    "values": dict,
+    "linkOpen": str,
+    "linkClose": str,
+}
+_THEME_VALUES = ("light", "dark")
+_RENDERER_VALUES = ("widget", "browser", "file", "none", "text")
+# Options that are Python-side dispatch only — never sent to the viewer as
+# part of the embedded-mode/settings-file `config` object (see resolve_config).
+_NON_VIEWER_OPTIONS = ("renderer",)
+# The viewer's "Special values" display overrides (structile.html's
+# renderMap/buildRenderMapPanel) — cosmetic-only, string-keyed, and travel to
+# the viewer as their own `renderMap` config field rather than folded into
+# the numeric `settings` object (see resolve_config).
+_RENDER_MAP_KEYS = ("forNull", "forEmpty", "values")
+# The viewer's cross-reference-value marker (structile.html's
+# linkSettings/buildLinkSettingsPanel) — a dict value/table cell wrapped
+# between these that names another dict/table in the document becomes a
+# clickable link. Own `links` config field (see resolve_config), keyed
+# `open`/`close` there — renamed from the Python-facing `linkOpen`/
+# `linkClose` (unlike _RENDER_MAP_KEYS, whose Python names already match
+# the viewer's own renderMap field names 1:1) since a bare top-level
+# `open`/`close` option name would be a poor, ambiguous public API.
+_LINK_KEYS = ("linkOpen", "linkClose")
+_LINK_KEYS_TO_FIELD = {"linkOpen": "open", "linkClose": "close"}
+
+
+def _validate(key: str, value: Any) -> None:
+    if key not in _OPTION_TYPES:
+        raise AttributeError(
+            f"structile: unknown option {key!r} (known options: "
+            + ", ".join(sorted(_OPTION_TYPES))
+            + ")"
+        )
+    if key == "theme":
+        if value not in _THEME_VALUES:
+            raise ValueError(f"structile: theme must be one of {_THEME_VALUES!r}, got {value!r}")
+        return
+    if key == "renderer":
+        if value not in _RENDERER_VALUES:
+            raise ValueError(f"structile: renderer must be one of {_RENDERER_VALUES!r}, got {value!r}")
+        return
+    if key in ("forNull", "forEmpty", "linkOpen", "linkClose"):
+        if not isinstance(value, str):
+            raise TypeError(f"structile: option {key!r} must be a str, got {type(value).__name__}")
+        return
+    if key == "values":
+        if not isinstance(value, dict) or not all(isinstance(k, str) and isinstance(v, str) for k, v in value.items()):
+            raise TypeError(f"structile: option 'values' must be a dict of str -> str, got {value!r}")
+        return
+    expected = _OPTION_TYPES[key]
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise TypeError(f"structile: option {key!r} must be a {expected.__name__}, got {type(value).__name__}")
+
+
+class Options:
+    """A namespace of viewer settings, matplotlib.rcParams-style.
+
+    Every attribute defaults to `None` (unset). Assigning `None` back to an
+    attribute restores that "use the viewer's default" state.
+    """
+
+    __slots__ = tuple(_OPTION_TYPES)
+
+    def __init__(self) -> None:
+        for key in _OPTION_TYPES:
+            object.__setattr__(self, key, None)
+
+    def __setattr__(self, key: str, value: Any) -> None:
+        if value is not None:
+            _validate(key, value)
+        object.__setattr__(self, key, value)
+
+    def as_dict(self) -> Dict[str, Any]:
+        """The currently-set (non-`None`) options, as a plain dict."""
+        return {key: getattr(self, key) for key in _OPTION_TYPES if getattr(self, key) is not None}
+
+
+options = Options()
+"""Module-level default `Options`, shared by every `open()` call that
+doesn't override a given option itself."""
+
+
+def set_option(name: str, value: Any) -> None:
+    """Set a module-level default option.
+
+        structile.set_option("theme", "dark")
+
+    Equivalent to `structile.options.<name> = value`. Pass `value=None` to
+    unset it again (falls back to the viewer's built-in default).
+    """
+    setattr(options, name, value)
+
+
+def get_option(name: str) -> Optional[Any]:
+    """Read a module-level default option (`None` if unset)."""
+    if name not in _OPTION_TYPES:
+        raise AttributeError(f"structile: unknown option {name!r}")
+    return getattr(options, name)
+
+
+def reset_option(name: str) -> None:
+    """Unset a module-level default option (falls back to the viewer default)."""
+    setattr(options, name, None)
+
+
+def replace_options(new_options: Options) -> None:
+    """Overwrite every module-level default option from `new_options`,
+    including keys left `None`/unset in it (which resets that option back to
+    unset here too, rather than leaving a stale previous value behind).
+
+    Used by `StructileWidget`'s "Set as default" action (see widget.py's
+    `_handle_settings_changed`): the browser-side settings panel's FULL
+    current state — not a diff — becomes the new baseline for every
+    `open()` call for the rest of this process, matplotlib.rcParams-
+    style, same as any other `set_option()` call.
+    """
+    for key in _OPTION_TYPES:
+        setattr(options, key, getattr(new_options, key))
+
+
+def resolve_config(overrides: Dict[str, Any], extra: Optional[Options] = None) -> Optional[Dict[str, Any]]:
+    """Merge module defaults + an optional per-call `Options` + per-call
+    keyword overrides (in that increasing order of precedence) into the
+    `config` object the viewer's embedded-mode protocol expects:
+    `{settings?: {...numeric keys...}, theme?: "light"|"dark", renderMap?:
+    {forNull?, forEmpty?, values?}, links?: {open?, close?}}`.
+
+    Returns `None` if nothing is set anywhere (config is entirely omitted,
+    same effect as an empty one).
+    """
+    if extra is not None and not isinstance(extra, Options):
+        raise TypeError(f"structile: config= must be an Options instance, got {type(extra).__name__}")
+    merged: Dict[str, Any] = dict(options.as_dict())
+    if extra is not None:
+        merged.update(extra.as_dict())
+    for key, value in overrides.items():
+        if value is None:
+            continue
+        _validate(key, value)
+        merged[key] = value
+    for key in _NON_VIEWER_OPTIONS:
+        merged.pop(key, None)
+    if not merged:
+        return None
+    theme = merged.pop("theme", None)
+    render_map = {key: merged.pop(key) for key in _RENDER_MAP_KEYS if key in merged}
+    links = {
+        _LINK_KEYS_TO_FIELD[key]: merged.pop(key) for key in _LINK_KEYS if key in merged
+    }
+    config: Dict[str, Any] = {}
+    if merged:
+        config["settings"] = merged
+    if theme is not None:
+        config["theme"] = theme
+    if render_map:
+        config["renderMap"] = render_map
+    if links:
+        config["links"] = links
+    return config
+
+
+def options_from_dict(mapping: Dict[str, Any]) -> Options:
+    """Build an `Options` instance from a plain dict — e.g. `config={"gap":
+    8, "forNull": "N/A"}` instead of `config=Options()` +
+    attribute-assignment. Same per-key validation as setting each attribute
+    individually (unknown key -> `AttributeError`, wrong type -> `TypeError`),
+    just collected up front instead of one at a time."""
+    opts = Options()
+    for key, value in mapping.items():
+        setattr(opts, key, value)
+    return opts
+
+
+def resolve_renderer(explicit: Optional[str] = None, extra: Optional[Options] = None) -> Optional[str]:
+    """Resolve the active renderer name, matplotlib-backend style, in
+    increasing precedence: an explicit `renderer=` argument -> the
+    `STRUCTILE_RENDERER` env var -> a per-call `config=Options()` -> the
+    module-level default (`structile.options.renderer` /
+    `set_option("renderer", ...)` / `use(...)`).
+
+    Returns `None` if nothing is set anywhere — the caller should then
+    auto-detect (see `render.detect_renderer`).
+    """
+    if explicit is not None:
+        _validate("renderer", explicit)
+        logger.debug("structile: renderer=%r (explicit)", explicit)
+        return explicit
+    env = os.environ.get("STRUCTILE_RENDERER")
+    if env:
+        _validate("renderer", env)
+        logger.debug("structile: renderer=%r (STRUCTILE_RENDERER)", env)
+        return env
+    if extra is not None and not isinstance(extra, Options):
+        raise TypeError(f"structile: config= must be an Options instance, got {type(extra).__name__}")
+    if extra is not None and extra.renderer is not None:
+        logger.debug("structile: renderer=%r (config=)", extra.renderer)
+        return extra.renderer
+    if options.renderer is not None:
+        logger.debug("structile: renderer=%r (module default)", options.renderer)
+    return options.renderer
+
+
+def use(renderer: str) -> None:
+    """Set the module-level default renderer, `matplotlib.use()`-style.
+
+        structile.use("browser")
+
+    Equivalent to `set_option("renderer", renderer)` / `options.renderer =
+    renderer`. See `structile.render.RENDERERS` for the valid names.
+    """
+    set_option("renderer", renderer)

structile/convert.py

@@ -0,0 +1,247 @@
+"""structile.convert() — format conversion outside the widget/notebook.
+
+Two built-in formats, "json" and "python" (Python-repr — the same dialect
+structile.html's own parsePythonRepr/serializePythonRepr read and
+write: dict keys always stringified, tuples collapse to lists, frozenset
+reads back as set — see _parse_python_repr/_serialize_python_repr below),
+are parsed and serialized entirely in Python: no extra dependency, no
+subprocess. Any other format ("xml"/"html", or a custom format like "ini")
+is not built in at all — it only exists via a caller-supplied interpreter
+script (the same interpretXML(xmlDocument)/serializeXML(value) — markup —
+or interpretText(text)/serializeText(value) — anything else — contract
+structile.open(..., interpreter=...) and structile.html's own
+embedded-mode interpreter loading use), which is JS and has to run as JS —
+see .interpreters.run_interpreter_source, which runs it in an embedded V8
+engine (the `mini-racer` package) rather than a real browser. That split IS
+the module's whole design: built-in <-> built-in needs nothing extra; the
+moment either side isn't "json"/"python", the optional 'mini-racer' package
+becomes required (no Node.js, no npm, no jsdom, no system install — see
+dom_lite.py/dom_lite.js for how "xml"/"html" get a DOM without a real
+browser or jsdom).
+"""
+from __future__ import annotations
+
+import ast
+import json
+import pathlib
+import re
+from typing import Any, Optional, Tuple, Union
+
+from ._paths import as_path_like, read_text
+from .interpreters import (
+    CANONICAL_EXT_FOR_FORMAT,
+    InterpreterSpec,
+    get_registered_interpreter,
+    resolve_candidates,
+    select_interpreter,
+)
+from .serialize import _normalize_float, normalize
+
+_FORMAT_BY_EXT = {".json": "json", ".py": "python", ".xml": "xml", ".html": "html", ".htm": "html"}
+# A bare "name.ext" string (no whitespace/braces/quotes — i.e. nothing that
+# could plausibly be literal data) with one of the recognized extensions:
+# almost certainly a path the caller meant to exist, so a missing file there
+# should say so clearly rather than silently falling through to being
+# sniffed — and likely misparsed — as literal source text instead. Only
+# covers the extensions _infer_source can sniff a format for without any
+# other context (see its own fallback for anything else) — a bare
+# "config.ini"-shaped missing path still gets a FileNotFoundError, just via
+# a different branch (no interpreter registered for ".ini" either).
+_BARE_FILENAME_RE = re.compile(r'^[^\s{}\[\]()\'"<>]+\.(json|py|xml|html?)$', re.IGNORECASE)
+
+
+def _canonical_ext_for(fmt: str) -> Optional[str]:
+    """The registry-lookup key for a format with no real file extension of
+    its own — `dst_format` is always just a string, never a path.
+    CANONICAL_EXT_FOR_FORMAT covers "xml"/"html" explicitly; any other
+    format falls back to "." + fmt, the same convention _infer_source's own
+    unrecognized-extension fallback (below) uses in the other direction."""
+    return CANONICAL_EXT_FOR_FORMAT.get(fmt) or (("." + fmt) if fmt else None)
+
+
+def convert(
+    src: Union[str, pathlib.Path],
+    dst_format: str,
+    interpreter: Optional[InterpreterSpec] = None,
+) -> str:
+    """Convert data from one of the viewer's formats to another, entirely
+    outside the widget/notebook — parse `src`, then serialize the result as
+    `dst_format`, returning the converted text. See README.md ("Converting
+    between formats") for the built-in-vs-JS-runtime boundary and examples.
+
+    src: a path (format inferred from its extension: .json/.py/.xml/.html —
+        or, once an interpreter is attached to it, any other extension too,
+        e.g. .ini) or a literal string of source text (sniffed: JSON, else
+        Python-repr, else XML if it looks like markup — there's no
+        `src_format=` parameter, so a literal string for any OTHER format
+        needs a `.` path instead, since there's no reliable way to sniff an
+        arbitrary text format from content alone the way XML's leading `<`
+        works).
+    dst_format: `"json"` | `"python"` | `"xml"` | `"html"` | any other
+        string an interpreter is registered/provided for (e.g. `"ini"`).
+    interpreter: a path to a `.js` interpreter script, raw JS source, or a
+        list of candidates tried in order (same contract as
+        `structile.open(..., interpreter=...)` — see `select_interpreter`) —
+        required whenever `src` or `dst_format` isn't `"json"`/`"python"`
+        and nothing is registered for the relevant extension (see
+        `register_interpreter`); needs the optional `mini-racer` package
+        (`pip install mini-racer`) to run it — no Node.js, no jsdom, no
+        system install (see interpreters.run_interpreter_source). Converting
+        purely between "json" and "python" needs nothing extra at all.
+    """
+    text, src_format, src_ext = _infer_source(src, interpreter)
+    value = _parse_by_format(text, src_format, interpreter, src_ext)
+    return _serialize_by_format(value, dst_format, interpreter, _canonical_ext_for(dst_format))
+
+
+def _infer_source(src: Union[str, pathlib.Path], interpreter: Optional[InterpreterSpec]) -> Tuple[str, str, Optional[str]]:
+    p = as_path_like(src)
+    if p is not None:
+        ext = p.suffix.lower()
+        fmt = _FORMAT_BY_EXT.get(ext)
+        if fmt is None:
+            # Not one of the built-in-recognized extensions — but a real
+            # format the moment an interpreter is actually attached to it
+            # (explicit interpreter=, or something registered), the same
+            # "only once something's attached" guard open()'s own
+            # markup-mode trigger uses. Otherwise this is almost certainly a
+            # genuine typo/unsupported file, so keep raising clearly rather
+            # than silently attempting a format nothing can ever satisfy.
+            if interpreter is not None or get_registered_interpreter(ext) is not None:
+                fmt = ext.lstrip(".")
+            else:
+                raise ValueError(f"structile.convert: can't infer a format from {p.name!r}'s extension")
+        return read_text(p), fmt, ext
+    if not isinstance(src, str):
+        raise TypeError("structile.convert: src must be a file path or a string of source text")
+    # Reached only when `src` is NOT an existing file (as_path_like already
+    # would have matched it above otherwise) — so a bare "name.ext"-shaped
+    # string here means a path that doesn't exist, not literal data.
+    if _BARE_FILENAME_RE.match(src.strip()):
+        raise FileNotFoundError(f"structile.convert: no such file: {src}")
+    stripped = src.lstrip()
+    if stripped.startswith("<"):
+        # Same heuristic as looksLikeHtmlDoc in structile.html.
+        looks_html = re.match(r"(?i)<!doctype\s+html|<html[\s>]", stripped) is not None
+        fmt = "html" if looks_html else "xml"
+        return src, fmt, CANONICAL_EXT_FOR_FORMAT[fmt]
+    try:
+        json.loads(src)  # try strict JSON first (the common case), same precedence as detectAndParseDataText
+        return src, "json", None
+    except ValueError:
+        return src, "python", None
+
+
+def _parse_by_format(text: str, fmt: str, interpreter: Optional[InterpreterSpec], ext: Optional[str]) -> Any:
+    if fmt == "json":
+        return json.loads(text)
+    if fmt == "python":
+        return _parse_python_repr(text)
+    # Any other format (xml/html/ini/...) runs through an interpreter —
+    # select_interpreter raises a clear error itself if none is available.
+    candidates = resolve_candidates(interpreter, ext)
+    return select_interpreter(candidates, fmt, op="parse", text=text, run=True).result
+
+
+def _serialize_by_format(value: Any, fmt: str, interpreter: Optional[InterpreterSpec], ext: Optional[str]) -> str:
+    if fmt == "json":
+        return json.dumps(normalize(value), indent=2)
+    if fmt == "python":
+        return _serialize_python_repr(value)
+    candidates = resolve_candidates(interpreter, ext)
+    return select_interpreter(candidates, fmt, op="serialize", value=value, run=True).result
+
+
+# ---- "python" (Python-repr) — parse -----------------------------------
+# A hand-rolled walk over the stdlib's own `ast`, not ast.literal_eval:
+# literal_eval can't parse `set()`/`frozenset()` (those are Call nodes, not
+# literal syntax) even though serializePythonRepr emits exactly that for an
+# empty set — so this needs to be literal_eval's node-walk plus that one
+# extra case, not literal_eval itself.
+def _parse_python_repr(text: str) -> Any:
+    try:
+        tree = ast.parse(text, mode="eval")
+    except SyntaxError as e:
+        raise ValueError(f"structile.convert: not valid Python literal syntax: {e}") from e
+    return _eval_literal_node(tree.body)
+
+
+def _eval_literal_node(node: ast.AST) -> Any:
+    if isinstance(node, ast.Constant):
+        if node.value is None or isinstance(node.value, (bool, int, float, str)):
+            return node.value
+        raise ValueError(f"structile.convert: unsupported literal {node.value!r} in Python-repr data")
+    if isinstance(node, ast.UnaryOp) and isinstance(node.op, (ast.USub, ast.UAdd)):
+        v = _eval_literal_node(node.operand)
+        return -v if isinstance(node.op, ast.USub) else v
+    if isinstance(node, ast.List):
+        return [_eval_literal_node(e) for e in node.elts]
+    if isinstance(node, ast.Tuple):
+        return [_eval_literal_node(e) for e in node.elts]  # tuples collapse to lists, matching the viewer's own dialect
+    if isinstance(node, ast.Set):
+        return {_eval_literal_node(e) for e in node.elts}
+    if isinstance(node, ast.Dict):
+        if any(k is None for k in node.keys):  # a None key node means **unpacking, e.g. {**other}
+            raise ValueError("structile.convert: dict unpacking (**) isn't valid Python-repr literal syntax")
+        return {
+            _js_like_key(_eval_literal_node(k)): _eval_literal_node(v)
+            for k, v in zip(node.keys, node.values)
+        }
+    if isinstance(node, ast.Call) and isinstance(node.func, ast.Name) and node.func.id in ("set", "frozenset"):
+        if node.keywords or len(node.args) > 1:
+            raise ValueError("structile.convert: set()/frozenset() takes 0 or 1 argument")
+        if not node.args:
+            return set()
+        inner = _eval_literal_node(node.args[0])
+        if isinstance(inner, (set, list)):
+            return set(inner)
+        raise ValueError("structile.convert: set()/frozenset() expects a list, tuple, or set argument")
+    raise ValueError(f"structile.convert: unsupported Python literal syntax ({ast.dump(node)})")
+
+
+def _js_like_key(value: Any) -> str:
+    """Mirrors parsePythonRepr's `String(k)` dict-key coercion (structile.html)
+    for the scalar cases that matter in practice; a composite
+    key (list/dict/set used as a key) is rare enough to not chase JS's exact
+    String() stringification of objects — falls back to Python's str()."""
+    if value is None:
+        return "null"
+    if value is True:
+        return "true"
+    if value is False:
+        return "false"
+    return str(value)
+
+
+# ---- "python" (Python-repr) — serialize --------------------------------
+# The exact inverse of the parse above, matching serializePythonRepr
+# (structile.html) — Python's own repr() would work for the scalar
+# cases too, but not for None/bool (Python's None/True/False spelling
+# happens to already match; kept explicit here for symmetry with the parser
+# above and because it's what pins down the dict/list/set container syntax).
+def _serialize_python_repr(value: Any) -> str:
+    if value is None:
+        return "None"
+    if isinstance(value, bool):
+        return "True" if value else "False"
+    if isinstance(value, int):
+        return str(value)  # exact for any size, same as serializePythonRepr's String(v) for a bigint
+    if isinstance(value, float):
+        return repr(_normalize_float(value))  # non-finite -> None -> "None"; ast can't parse bare inf/nan anyway
+    if isinstance(value, str):
+        return repr(value)
+    if isinstance(value, (set, frozenset)):
+        if not value:
+            return "set()"
+        try:
+            items = sorted(value)
+        except TypeError:
+            items = list(value)
+        return "{" + ", ".join(_serialize_python_repr(v) for v in items) + "}"
+    if isinstance(value, (list, tuple)):
+        return "[" + ", ".join(_serialize_python_repr(v) for v in value) + "]"
+    if isinstance(value, dict):
+        if not value:
+            return "{}"
+        return "{" + ", ".join(f"{_serialize_python_repr(k)}: {_serialize_python_repr(v)}" for k, v in value.items()) + "}"
+    raise TypeError(f"structile.convert: don't know how to serialize a value of type {type(value).__name__!r} to python-repr")

structile/dom_lite.js

@@ -0,0 +1,70 @@
+// dom_lite.js — minimal DOM built from a plain Python-parsed tree (see
+// structile/_dom_lite.py), for structile.convert()'s xml/html
+// interpreter path. Loaded into the same mini-racer context as the
+// interpreter script itself, ahead of it — see interpreters.py's
+// run_interpreter_source, which is the only place this ever runs (not part
+// of the browser bundle: structile.html hands interpreters a REAL
+// browser DOM via its own DOMParser, untouched by any of this).
+//
+// NOT jsdom, not a general DOM implementation — only the subset
+// interpretXML/serializeXML scripts actually use: tagName, getAttribute,
+// children, textContent, plus documentElement/doctype/body at the document
+// level (see README.md's "Custom formats via an interpreter" section for
+// the documented contract). A custom interpreter reaching for anything
+// beyond this (namespaces, siblings, attributes as a NamedNodeMap,
+// querySelector with a real CSS selector, ...) isn't supported here.
+
+function __structileBuildElement(node){
+  const attrs = node.attrs || {};
+  const children = (node.children || []).map(__structileBuildElement);
+  return {
+    tagName: node.tag,
+    children: children,
+    textContent: node.text || "",
+    getAttribute: function(name){
+      return Object.prototype.hasOwnProperty.call(attrs, name) ? attrs[name] : null;
+    },
+    hasAttribute: function(name){ return Object.prototype.hasOwnProperty.call(attrs, name); },
+    attributes: attrs,
+    // Bare tag-name lookup only (no class/id/attribute selectors) — a depth-
+    // first search of this element's own descendants, matching the one way
+    // the bundled interpreters ever call this (generic_xml.js's childElementsXml
+    // uses .children directly instead; this exists for parity/forward use).
+    querySelector: function(tag){
+      const want = String(tag).toLowerCase();
+      const stack = this.children.slice();
+      while (stack.length){
+        const cur = stack.shift();
+        if (cur.tagName.toLowerCase() === want) return cur;
+        stack.push.apply(stack, cur.children);
+      }
+      return null;
+    },
+  };
+}
+function __structileBuildDocument(payload){
+  return {
+    documentElement: __structileBuildElement(payload.root),
+    doctype: payload.hasDoctype ? { name: "html" } : null,
+    body: payload.body ? __structileBuildElement(payload.body) : null,
+  };
+}
+// JSON has no Set — mirrors structile/interpreters.py's _mark_sets/
+// _unmark_sets on the Python side of this exact same boundary (a Python
+// set/frozenset going INTO this context, or a JS Set an interpreter
+// constructs going back OUT — see run_interpreter_source).
+const __STRUCTILE_SET_MARK = "__structile_set__";
+function __structileMarkSets(v){
+  if (v instanceof Set) return { [__STRUCTILE_SET_MARK]: Array.from(v).map(__structileMarkSets) };
+  if (Array.isArray(v)) return v.map(__structileMarkSets);
+  if (v && typeof v === "object"){ const o = {}; for (const k of Object.keys(v)) o[k] = __structileMarkSets(v[k]); return o; }
+  return v;
+}
+function __structileUnmarkSets(v){
+  if (v && typeof v === "object" && !Array.isArray(v) &&
+      Object.keys(v).length === 1 && Array.isArray(v[__STRUCTILE_SET_MARK]))
+    return new Set(v[__STRUCTILE_SET_MARK].map(__structileUnmarkSets));
+  if (Array.isArray(v)) return v.map(__structileUnmarkSets);
+  if (v && typeof v === "object"){ const o = {}; for (const k of Object.keys(v)) o[k] = __structileUnmarkSets(v[k]); return o; }
+  return v;
+}