structile 6.28.0__tar.gz → 6.30.0__tar.gz

{structile-6.28.0/structile.egg-info → structile-6.30.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: structile
-Version: 6.28.0
+Version: 6.30.0
 Summary: A spatial editor and diff tool for structured data, inline in Jupyter
 License-Expression: Apache-2.0
 Requires-Python: >=3.8
@@ -94,6 +94,31 @@ formatting, rather than a re-serialization.
 big-int/set handling included — and returns the resulting JSON-safe
 structure directly, with no rendering at all, if that's all you want.
 
+Any other object — `datetime.date`, `Decimal`, `UUID`, an `Enum` member,
+your own dataclass — is shown as its `repr()` text (an enum member as
+`Color.RED`) in its own color, and can be edited in place as that text:
+double-click `datetime.date(2020, 1, 1)`, type `datetime.date(2021, 2, 3)`.
+After Save, `h.value` holds real objects again: the original object
+wherever you didn't touch it, and a new one built from your text where you
+did. Your text is never run with `eval()`. Only the standard-library types
+whose repr rebuilds them (`datetime.*`, `Decimal`, `Fraction`, `UUID`,
+`pathlib` paths, `zoneinfo.ZoneInfo`, `complex`) and the classes already
+present in your data are allowed. If an edit can't be turned into an
+object (`datetime.date(2020, 13, 1)`, an unknown name), the viewer says so
+and `h.value` keeps its previous value.
+
+Pass `default=` (to `open()`, `diff()`, or `normalize()` itself) to show
+such objects some other way instead, same escape hatch as
+`json.dumps(..., default=...)`: it's called with the object and its return
+value takes the object's place (normalized in turn, so it can return
+anything `normalize()` already understands, not just a JSON scalar).
+`default=str`, for instance, shows a date as the plain string
+`"2020-01-01"`:
+
+```python
+st.open(my_data, default=str)   # objects -> str(value), a plain string
+```
+
 ## Renderers
 
 `open()` doesn't hardcode "inline Jupyter widget" — it renders
@@ -474,8 +499,14 @@ logging.basicConfig(level=logging.DEBUG)
 
 - Fixed iframe height (`height=`, default `600`) — no auto-resize to content
   yet.
-- Plain numpy arrays aren't handled (only numpy *scalars*) — call
-  `.tolist()` first if you need to show one.
+- Plain numpy arrays are shown as their `repr()` text, not as a table, and
+  that text can't be edited back into an array — call `.tolist()` first if
+  you need to see or edit the values.
+- An object used as a dict *key* is shown as its `str()` and comes back as
+  that string — only values are revived into objects.
+- A class defined inside a function has a repr like
+  `f.<locals>.Point(x=1)`, which isn't Python syntax, so its objects can be
+  shown and handed back untouched but not edited.
 - A source dict with keys that collide once stringified (e.g. both `1` and
   `"1"` as separate keys) will collide in the displayed result too — this
   is a fundamental JSON limitation (object keys are always strings), not

{structile-6.28.0 → structile-6.30.0}/README.pypi.md

@@ -66,6 +66,31 @@ formatting, rather than a re-serialization.
 big-int/set handling included — and returns the resulting JSON-safe
 structure directly, with no rendering at all, if that's all you want.
 
+Any other object — `datetime.date`, `Decimal`, `UUID`, an `Enum` member,
+your own dataclass — is shown as its `repr()` text (an enum member as
+`Color.RED`) in its own color, and can be edited in place as that text:
+double-click `datetime.date(2020, 1, 1)`, type `datetime.date(2021, 2, 3)`.
+After Save, `h.value` holds real objects again: the original object
+wherever you didn't touch it, and a new one built from your text where you
+did. Your text is never run with `eval()`. Only the standard-library types
+whose repr rebuilds them (`datetime.*`, `Decimal`, `Fraction`, `UUID`,
+`pathlib` paths, `zoneinfo.ZoneInfo`, `complex`) and the classes already
+present in your data are allowed. If an edit can't be turned into an
+object (`datetime.date(2020, 13, 1)`, an unknown name), the viewer says so
+and `h.value` keeps its previous value.
+
+Pass `default=` (to `open()`, `diff()`, or `normalize()` itself) to show
+such objects some other way instead, same escape hatch as
+`json.dumps(..., default=...)`: it's called with the object and its return
+value takes the object's place (normalized in turn, so it can return
+anything `normalize()` already understands, not just a JSON scalar).
+`default=str`, for instance, shows a date as the plain string
+`"2020-01-01"`:
+
+```python
+st.open(my_data, default=str)   # objects -> str(value), a plain string
+```
+
 ## Renderers
 
 `open()` doesn't hardcode "inline Jupyter widget" — it renders
@@ -446,8 +471,14 @@ logging.basicConfig(level=logging.DEBUG)
 
 - Fixed iframe height (`height=`, default `600`) — no auto-resize to content
   yet.
-- Plain numpy arrays aren't handled (only numpy *scalars*) — call
-  `.tolist()` first if you need to show one.
+- Plain numpy arrays are shown as their `repr()` text, not as a table, and
+  that text can't be edited back into an array — call `.tolist()` first if
+  you need to see or edit the values.
+- An object used as a dict *key* is shown as its `str()` and comes back as
+  that string — only values are revived into objects.
+- A class defined inside a function has a repr like
+  `f.<locals>.Point(x=1)`, which isn't Python syntax, so its objects can be
+  shown and handed back untouched but not edited.
 - A source dict with keys that collide once stringified (e.g. both `1` and
   `"1"` as separate keys) will collide in the displayed result too — this
   is a fundamental JSON limitation (object keys are always strings), not

structile-6.30.0/VERSION

@@ -0,0 +1 @@
+6.30.0

{structile-6.28.0 → structile-6.30.0}/structile/__init__.py

@@ -28,6 +28,7 @@ from ._paths import (
     set_viewer_html,
     strict_json_loads as _strict_json_loads,
 )
+from ._pyobjects import PyObjects as _PyObjects
 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 .custom_html import build_custom_html
@@ -291,7 +292,11 @@ def open(
         **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
+            `kvCols`, `maxWidthFrac`, and the nested-container cap's
+            `childCap`/`childStep` with its `limitChildren` on/off switch —
+            a bool, like `cellContainerBadges` — and `warnElements`, the
+            page-element count past which a redraw shows a "large view"
+            warning, 0 = never), `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,
@@ -349,12 +354,15 @@ def open(
         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
+        default: called on any value that isn't one of `obj`'s own JSON-mappable
             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`.
+            `default=str` displays a date as the plain string `"2020-01-01"`.
+            Without it, such an object (`datetime.date`, `Decimal`, your own
+            dataclass, ...) is shown as its `repr()` text, editable in place,
+            and `.value` holds a real object again after Save: the original
+            one if its text wasn't touched, otherwise one rebuilt from the
+            edited text. See `structile.normalize`.
     """
     if isinstance(config, dict):
         config = options_from_dict(config)
@@ -385,6 +393,7 @@ def open(
             ),
         )
         payload.name = name or payload.name
+        payload.source_file_name = source_path.name if source_path is not None else None
         payload.config = embed_config
         _logger.debug("structile: markup mode (%s)", payload.format)
         widget = None
@@ -395,6 +404,7 @@ def open(
                 interpreter_source=payload.interpreter_source or "",
                 interpreter_candidates_by_format=payload.interpreter_candidates_by_format or {},
                 data_name=payload.name,
+                source_file_name=payload.source_file_name or "",
                 height=height,
                 config_json=config_json,
                 value=payload.text,
@@ -416,7 +426,14 @@ def open(
         # 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)
+    py_objects = _PyObjects()
+    normalized = normalize(data, default, objects=py_objects)
+    # Same revive step a Save runs (see StructileWidget._handle_save), so
+    # .value holds the same kind of thing before and after an untouched
+    # Save — the original objects, never their {"__pyrepr__": ...} tags.
+    # Lenient here: a tag in a loaded FILE may name a type this process
+    # has never seen, which is no reason to refuse to show it.
+    value = py_objects.revive(normalized, strict=False)
     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
@@ -431,19 +448,22 @@ def open(
     # 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)
+    source_file_name = source_path.name if source_path is not None else None
     widget = None
     if resolved_renderer == "widget":
         widget = StructileWidget(
             value_json=text,
             data_name=display_name,
+            source_file_name=source_file_name or "",
             height=height,
             config_json=config_json,
-            value=normalized,
+            value=value,
             source_path=source_path,
             save_path=save_path,
+            py_objects=py_objects,
         )
-    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)
+    payload = _Payload(text=text, format="json", name=display_name, config=embed_config, source_file_name=source_file_name)
+    return _render(payload, value=value, renderer=resolved_renderer, widget=widget, out=out, auto_open=auto_open)
 
 
 def _resolve_diff_side(
@@ -487,8 +507,9 @@ def _resolve_diff_side(
         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)
+    py_objects = _PyObjects()
+    normalized = normalize(data, default, objects=py_objects)
+    return _Payload(text=json.dumps(normalized, indent=2), format="json", name=inferred_name, py_objects=py_objects)
 
 
 def diff(

structile-6.30.0/structile/_pyobjects.py

@@ -0,0 +1,254 @@
+"""Python objects JSON has no slot for (`datetime.date`, `Decimal`, a
+user's own dataclass, ...) — shown and edited in the viewer as their
+`repr()` text, and turned back into real objects when edited data comes
+home on Save.
+
+Wire format: `normalize()` replaces such an object with a one-key tag,
+`{"__pyrepr__": "datetime.date(2020, 1, 1)"}`. The viewer revives that tag
+into its own opaque leaf type (`PyExpr` in structile.html) — displayed as
+the bare text, edited as the bare text — and writes the same tag back out on
+Save, so JSON stays the only thing that ever crosses the host<->viewer
+boundary. `PyObjects.revive()` then walks the saved JSON and turns each tag
+back into an object:
+
+  - A tag whose text is unchanged from what `normalize()` produced resolves
+    to the ORIGINAL object (not a rebuilt copy), so an untouched value keeps
+    its identity — even one whose repr can't be rebuilt at all, like
+    `<Foo object at 0x7f...>`. Several originals sharing one text are
+    handed out in order, so two equal-but-distinct mutable objects don't
+    come back as one aliased instance.
+  - An edited (or newly typed) text is rebuilt by a restricted AST walk —
+    never `eval()`: the text comes from a browser page or a file on disk.
+    Only literals, containers, and calls/names found in the constructor
+    registry are allowed. The registry starts with the stdlib types whose
+    repr round-trips (`_BUILTIN_TYPES`) and learns every type `normalize()`
+    wrapped whose repr is shaped like a call to that type itself
+    (`Point(x=1, y=2)` for a class named `Point`) — so the classes already
+    present in the data are editable with no registration step.
+
+Enum members are the one deliberate exception to "the text is `repr()`":
+`repr(Color.RED)` is `<Color.RED: 1>`, which isn't Python syntax, so a
+member is written as `Color.RED` instead, and every member of its class is
+registered under that spelling (so editing it to `Color.GREEN` works).
+"""
+from __future__ import annotations
+
+import ast
+import datetime
+import decimal
+import enum
+import fractions
+import pathlib
+import uuid
+from typing import Any, Dict, List, Mapping, Optional
+
+PYREPR_KEY = "__pyrepr__"
+
+
+class PyReprError(ValueError):
+    """An edited Python-object text couldn't be turned back into an object
+    (bad syntax, a name outside the registry, or the constructor itself
+    refused its arguments)."""
+
+
+def _builtin_types() -> Dict[str, Any]:
+    types: Dict[str, Any] = {
+        "datetime.date": datetime.date,
+        "datetime.datetime": datetime.datetime,
+        "datetime.time": datetime.time,
+        "datetime.timedelta": datetime.timedelta,
+        "datetime.timezone": datetime.timezone,
+        "datetime.timezone.utc": datetime.timezone.utc,
+        "Decimal": decimal.Decimal,
+        "Fraction": fractions.Fraction,
+        "UUID": uuid.UUID,
+        "complex": complex,
+        "PurePosixPath": pathlib.PurePosixPath,
+        "PureWindowsPath": pathlib.PureWindowsPath,
+        # Only this platform's concrete Path class — the other one refuses
+        # to instantiate here anyway (PosixPath on Windows or vice versa).
+        type(pathlib.Path()).__name__: type(pathlib.Path()),
+    }
+    try:
+        import zoneinfo  # Python 3.9+
+    except ImportError:
+        pass
+    else:
+        types["zoneinfo.ZoneInfo"] = zoneinfo.ZoneInfo
+    return types
+
+
+_BUILTIN_TYPES = _builtin_types()
+
+
+def is_tag(value: Any) -> bool:
+    return isinstance(value, dict) and len(value) == 1 and isinstance(value.get(PYREPR_KEY), str)
+
+
+def object_text(obj: Any) -> str:
+    """The text a Python object is shown and edited as — its `repr()`,
+    except for enum members (see the module docstring). A `__repr__` that
+    raises falls back to `object`'s own `<Foo object at 0x...>` rather than
+    failing the whole `open()` call over one unprintable value."""
+    if isinstance(obj, enum.Enum):
+        return f"{type(obj).__qualname__}.{obj.name}"
+    try:
+        text = repr(obj)
+    except Exception:
+        text = object.__repr__(obj)
+    return text if isinstance(text, str) else object.__repr__(obj)
+
+
+def _dotted_name(node: ast.AST) -> Optional[str]:
+    if isinstance(node, ast.Name):
+        return node.id
+    if isinstance(node, ast.Attribute):
+        base = _dotted_name(node.value)
+        return None if base is None else base + "." + node.attr
+    return None
+
+
+def _callee_name(text: str) -> Optional[str]:
+    """`"datetime.date"` for `"datetime.date(2020, 1, 1)"`; `None` when the
+    text isn't a single call expression."""
+    try:
+        tree = ast.parse(text.strip(), mode="eval")
+    except (SyntaxError, ValueError):
+        return None
+    return _dotted_name(tree.body.func) if isinstance(tree.body, ast.Call) else None
+
+
+def parse_object_text(text: str, types: Mapping[str, Any]) -> Any:
+    """Rebuild an object from its text, allowing nothing beyond literals,
+    containers, and the names/calls listed in `types`. Raises
+    `PyReprError` for anything else, and for a constructor that refuses its
+    arguments (`datetime.date(2020, 13, 1)`)."""
+    try:
+        tree = ast.parse(text.strip(), mode="eval")
+    except (SyntaxError, ValueError) as e:
+        raise PyReprError(f"{text!r} is not a valid Python expression ({e.msg if isinstance(e, SyntaxError) else e})") from e
+    try:
+        return _eval_node(tree.body, types)
+    except PyReprError:
+        raise
+    except Exception as e:  # the constructor itself refused (ValueError/TypeError/...)
+        raise PyReprError(f"can't rebuild {text!r}: {type(e).__name__}: {e}") from e
+
+
+def _lookup(name: Optional[str], types: Mapping[str, Any]) -> Any:
+    if name is None or name not in types:
+        known = ", ".join(sorted(types))
+        raise PyReprError(f"{name or 'this expression'!r} is not a known Python type here (known: {known})")
+    return types[name]
+
+
+def _eval_node(node: ast.AST, types: Mapping[str, Any]) -> Any:
+    if isinstance(node, ast.Constant):
+        if node.value is Ellipsis:
+            # A summarized repr (numpy's `array([0, 1, ..., 999])`) — rebuilding
+            # it would silently produce something other than what was shown.
+            raise PyReprError("a summarized repr containing '...' can't be rebuilt")
+        return node.value
+    if isinstance(node, ast.Call):
+        fn = _lookup(_dotted_name(node.func), types)
+        if not callable(fn):
+            raise PyReprError(f"{_dotted_name(node.func)!r} is not callable")
+        args: List[Any] = []
+        for a in node.args:
+            if isinstance(a, ast.Starred):
+                raise PyReprError("*args unpacking isn't supported")
+            args.append(_eval_node(a, types))
+        kwargs: Dict[str, Any] = {}
+        for kw in node.keywords:
+            if kw.arg is None:
+                raise PyReprError("**kwargs unpacking isn't supported")
+            kwargs[kw.arg] = _eval_node(kw.value, types)
+        return fn(*args, **kwargs)
+    if isinstance(node, (ast.Name, ast.Attribute)):
+        return _lookup(_dotted_name(node), types)  # e.g. datetime.timezone.utc, Color.RED
+    if isinstance(node, ast.UnaryOp) and isinstance(node.op, (ast.USub, ast.UAdd)):
+        v = _eval_node(node.operand, types)
+        return -v if isinstance(node.op, ast.USub) else +v
+    if isinstance(node, ast.BinOp) and isinstance(node.op, (ast.Add, ast.Sub)):
+        # Only complex literals like (1+2j) — never general arithmetic.
+        left, right = _eval_node(node.left, types), _eval_node(node.right, types)
+        if isinstance(left, (int, float)) and isinstance(right, complex):
+            return left + right if isinstance(node.op, ast.Add) else left - right
+        raise PyReprError("arithmetic isn't supported, only complex literals like (1+2j)")
+    # Real Python containers here, not the viewer's JSON dialect: a tuple
+    # argument to a constructor has to stay a tuple.
+    if isinstance(node, ast.List):
+        return [_eval_node(e, types) for e in node.elts]
+    if isinstance(node, ast.Tuple):
+        return tuple(_eval_node(e, types) for e in node.elts)
+    if isinstance(node, ast.Set):
+        return {_eval_node(e, types) for e in node.elts}
+    if isinstance(node, ast.Dict):
+        if any(k is None for k in node.keys):
+            raise PyReprError("dict unpacking (**) isn't supported")
+        return {_eval_node(k, types): _eval_node(v, types) for k, v in zip(node.keys, node.values)}
+    raise PyReprError(f"unsupported Python syntax: {type(node).__name__}")
+
+
+class PyObjects:
+    """One `open()`/`set_value()` call's worth of wrapped objects — the
+    originals (for identity-preserving revival of untouched values) and the
+    constructor registry (stdlib types plus every type learned from the
+    data itself). See the module docstring."""
+
+    def __init__(self) -> None:
+        self._originals: Dict[str, List[Any]] = {}
+        self.types: Dict[str, Any] = dict(_BUILTIN_TYPES)
+
+    def wrap(self, obj: Any) -> Dict[str, str]:
+        text = object_text(obj)
+        self._originals.setdefault(text, []).append(obj)
+        self._learn_type(obj, text)
+        return {PYREPR_KEY: text}
+
+    def _learn_type(self, obj: Any, text: str) -> None:
+        cls = type(obj)
+        if isinstance(obj, enum.Enum):
+            for member in cls:
+                self.types.setdefault(f"{cls.__qualname__}.{member.name}", member)
+            return
+        name = _callee_name(text)
+        # Only when the repr names this very class (`Point(x=1)` for class
+        # Point, `datetime.date(...)` for date) — never guess a constructor
+        # for a repr like numpy's `array([...])` (class ndarray).
+        if name is not None and name.rsplit(".", 1)[-1] == cls.__name__:
+            self.types.setdefault(name, cls)
+
+    def revive(self, value: Any, *, strict: bool = True) -> Any:
+        """Turn every `{"__pyrepr__": text}` tag in a JSON value back into
+        a Python object. `strict=False` keeps a tag that can't be rebuilt
+        as-is instead of raising — for data loaded from a file, which may
+        name types this process has never seen."""
+        pool = {text: list(objs) for text, objs in self._originals.items()}
+        return self._revive(value, pool, strict)
+
+    def _revive(self, value: Any, pool: Dict[str, List[Any]], strict: bool) -> Any:
+        if isinstance(value, dict):
+            if is_tag(value):
+                return self._from_text(value[PYREPR_KEY], pool, value, strict)
+            return {k: self._revive(v, pool, strict) for k, v in value.items()}
+        if isinstance(value, list):
+            return [self._revive(v, pool, strict) for v in value]
+        return value
+
+    def _from_text(self, text: str, pool: Dict[str, List[Any]], tag: Dict[str, str], strict: bool) -> Any:
+        originals = pool.get(text)
+        if originals:
+            return originals.pop(0)
+        try:
+            return parse_object_text(text, self.types)
+        except PyReprError:
+            seen = self._originals.get(text)
+            if seen:
+                # More copies than originals (a duplicated row) of an object
+                # that can't be rebuilt from its text — reuse the original
+                # rather than refuse an edit that never touched its text.
+                return seen[-1]
+            if strict:
+                raise
+            return tag

{structile-6.28.0 → structile-6.30.0}/structile/config.py

@@ -55,6 +55,11 @@ _OPTION_TYPES: Dict[str, type] = {
     "kvRows": int,
     "kvCols": int,
     "maxWidthFrac": float,
+    "cellContainerBadges": bool,
+    "limitChildren": bool,
+    "childCap": int,
+    "childStep": int,
+    "warnElements": int,
     "theme": str,
     "renderer": str,
     "forNull": str,
@@ -109,6 +114,13 @@ def _validate(key: str, value: Any) -> None:
             raise TypeError(f"structile: option 'values' must be a dict of str -> str, got {value!r}")
         return
     expected = _OPTION_TYPES[key]
+    if expected is bool:
+        # The viewer's checkbox settings (SETTINGS_SCHEMA `type: "checkbox"`)
+        # — a real bool only, never 0/1: the viewer's own
+        # mergeSettingsWithEmbedded accepts nothing else for these keys.
+        if not isinstance(value, bool):
+            raise TypeError(f"structile: option {key!r} must be a bool, got {type(value).__name__}")
+        return
     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__}")
 

{structile-6.28.0 → structile-6.30.0}/structile/custom_html.py

@@ -31,7 +31,7 @@ runs this function, instead of by whoever later opens the file.
 from __future__ import annotations
 
 import pathlib
-from typing import Dict, Optional, Union
+from typing import Any, Dict, Optional, Union
 
 from ._paths import find_viewer_html, inject_global_script, read_interpreter
 from .manifest import ManifestSource, load_manifest
@@ -59,11 +59,15 @@ def build_custom_html(
     NOT the wrapping object. Each entry names its own `extensions` (one or
     several) and `format`, and one build freely mixes the two contracts
     (`"xml"`/`"html"` use `interpretXML`/`serializeXML`, every other
-    `format` string uses `interpretText`/`serializeText`). If two entries
-    claim the same extension the later one silently wins — no error — so
-    keep the list unambiguous. Extensions absent from the manifest behave
-    exactly as in the stock viewer, and the built-in JSON/Python-repr/CSV
-    formats need no entry at all.
+    `format` string uses `interpretText`/`serializeText`). An entry with
+    `binary: true` (implied by `format: "bin"`) reads BYTES: the viewer
+    routes a dropped file of that extension straight to its
+    `interpretText`, one character per byte, without ever sniffing or
+    decoding it as text — see `structile.manifest.InterpreterManifestEntry`.
+    If two entries claim the same extension the later one silently wins —
+    no error — so keep the list unambiguous. Extensions absent from the
+    manifest behave exactly as in the stock viewer, and the built-in
+    JSON/Python-repr/CSV formats need no entry at all.
 
     `source_html`: the base HTML to bake into — defaults to
         `find_viewer_html()`'s own resolution (the dev source next to this
@@ -78,11 +82,11 @@ def build_custom_html(
         if source_html is not None
         else find_viewer_html().read_text(encoding="utf-8")
     )
-    baked: Dict[str, Dict[str, str]] = {}
+    baked: Dict[str, Dict[str, Any]] = {}
     for entry in entries:
         text = read_interpreter(entry.path)
         for ext in entry.extensions:
-            baked[_normalize_ext(ext)] = {"format": entry.format, "source": text, "name": entry.name}
+            baked[_normalize_ext(ext)] = {"format": entry.format, "source": text, "name": entry.name, "binary": entry.binary}
     html_text = inject_global_script(base_html, "__STRUCTILE_BAKED_INTERPRETERS__", baked)
     if output is not None:
         pathlib.Path(output).write_text(html_text, encoding="utf-8")

{structile-6.28.0 → structile-6.30.0}/structile/manifest.py

@@ -44,12 +44,25 @@ class InterpreterManifestEntry:
     `format`: `"xml"`/`"html"` (the DOM contract) or any other string (the
         `interpretText` contract) — same meaning as `structile.open()`'s
         own `format=` argument.
+    `binary`: `True` when this interpreter reads BYTES rather than text —
+        the viewer then hands a dropped file of one of these `extensions`
+        to `interpretText` one character per byte (structile.html's
+        `runBinaryInterpreter`), never decoded, never line-ending-
+        normalized, and regardless of whether the bytes happen to sniff as
+        text. Defaults to `format == "bin"` (what the viewer's own "Save
+        viewer with interpreter…" writes for a binary session), so an
+        explicit flag is only needed for a binary format that wants a
+        different `format` label. An explicit flag rather than "whatever
+        the byte sniff says": a bespoke format's bytes can look like text
+        (no NUL, few control bytes) and would otherwise reach the
+        interpreter decoded and CRLF-normalized — i.e. corrupted.
     """
 
     extensions: List[str]
     path: ManifestInterpreterPath
     name: str
     format: str
+    binary: bool = False
 
 
 def _entry_from_dict(d: Dict[str, Any], *, base_dir: Optional[pathlib.Path]) -> InterpreterManifestEntry:
@@ -59,7 +72,9 @@ def _entry_from_dict(d: Dict[str, Any], *, base_dir: Optional[pathlib.Path]) ->
     path = d["path"]
     if base_dir is not None and isinstance(path, str) and not pathlib.Path(path).is_absolute():
         path = base_dir / path
-    return InterpreterManifestEntry(extensions=list(extensions), path=path, name=d["name"], format=d["format"])
+    fmt = d["format"]
+    binary = d["binary"] if "binary" in d else fmt == "bin"
+    return InterpreterManifestEntry(extensions=list(extensions), path=path, name=d["name"], format=fmt, binary=bool(binary))
 
 
 ManifestSource = Union[str, pathlib.Path, Sequence[Union[Dict[str, Any], InterpreterManifestEntry]]]

{structile-6.28.0 → structile-6.30.0}/structile/render.py

@@ -27,7 +27,7 @@ import sys
 import tempfile
 import uuid
 import webbrowser
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from typing import Any, Dict, List, Optional, Union
 
 from ._log import logger
@@ -123,9 +123,22 @@ class Payload:
     # browser can decide for itself.
     interpreter_candidates_by_format: Optional[Dict[str, List[str]]] = None
     config: Optional[Dict[str, Any]] = None
+    # The real on-disk name (`source_path.name`, extension and all) when
+    # this was loaded from an actual file; None for an in-memory value or a
+    # literal string. `name` is only the display stem, so without this the
+    # viewer can't tell `open("x.xml")` from `open("<x/>", format="xml")`
+    # and shows both as "no file on disk" (see currentSourceFileName in
+    # structile.html).
+    source_file_name: Optional[str] = None
+    # The Python objects normalize() tagged while building `text` (see
+    # _pyobjects.py) — Python-side only, never part of the snapshot, so a
+    # widget built from this payload can revive saved tags back into them.
+    py_objects: Any = field(default=None, repr=False, compare=False)
 
     def to_snapshot_dict(self) -> Dict[str, Any]:
         d: Dict[str, Any] = {"text": self.text, "format": self.format, "name": self.name}
+        if self.source_file_name:
+            d["sourceFileName"] = self.source_file_name
         if self.interpreter_source:
             d["interpreterSource"] = self.interpreter_source
         if self.interpreter_candidates_by_format: