structile 6.0.0__py3-none-any.whl

structile/static/widget.js

@@ -0,0 +1,185 @@
+// anywidget front-end: mounts structile.html inside an iframe and
+// drives it purely through its documented embedded-mode postMessage
+// protocol (see the "EMBEDDED MODE" section of structile.html) —
+// this file has no knowledge of the viewer's internals beyond that
+// contract, so it stays correct across viewer changes as long as the
+// protocol does. Shared by both StructileWidget ("value" mode, single
+// document, read-write) and StructileDiffWidget ("diff" mode, two-sided,
+// read-only graph) — see widget.py's own `mode` trait on each class.
+function render({ model, el }) {
+  const iframe = document.createElement("iframe");
+  iframe.style.width = "100%";
+  iframe.style.height = model.get("height") + "px";
+  iframe.style.border = "0px";
+  iframe.style.borderRadius = "0px";
+  iframe.style.display = "block";
+  // srcdoc (not src) — the viewer HTML is delivered inline over the widget
+  // model, not fetched from a URL, so this works the same whether the
+  // notebook is local or hosted.
+  iframe.srcdoc = model.get("viewer_html");
+  el.appendChild(iframe);
+  model.on("change:height", () => {
+    iframe.style.height = model.get("height") + "px";
+  });
+
+  if (model.get("mode") === "diff") return renderDiff(model, iframe);
+  return renderValue(model, iframe);
+}
+
+// A model trait holding a single interpreter source, or a list of candidates
+// the viewer tries itself (tryInterpreterCandidates in structile.html) —
+// shared truthiness check for the three traits shaped this way
+// (interpreter_source, left_interpreter_source, right_interpreter_source).
+function hasInterpreterSource(source) {
+  return typeof source === "string" ? !!source : Array.isArray(source) && source.length > 0;
+}
+
+// Forwards a viewer -> host structile-save-requested message on to Python's on_msg
+// (see widget.py's _on_custom_msg) — shared by renderValue/renderDiff, which
+// differ only in whether a `side` field is also present (diff mode only).
+function forwardSaveRequested(model, msg, extra) {
+  model.send({
+    type: "structile-save-requested",
+    format: msg.format,
+    ext: msg.ext,
+    fileName: msg.fileName,
+    isSaveAs: !!msg.isSaveAs,
+    content: msg.content,
+    ...extra,
+  });
+}
+
+// Forwards a viewer -> host structile-settings-changed message on to Python's
+// on_msg (see widget.py's _handle_settings_changed) — a one-off event, same
+// custom-message channel as structile-save-requested (see the comment on
+// forwardSaveRequested/onViewerMessage below for why this isn't a trait).
+function forwardSettingsChanged(model, msg) {
+  model.send({
+    type: "structile-settings-changed",
+    settings: msg.settings,
+    renderMap: msg.renderMap,
+    links: msg.links,
+    theme: msg.theme,
+  });
+}
+
+function renderValue(model, iframe) {
+  function sendInit() {
+    if (!iframe.contentWindow) return;
+    // raw_format non-empty, OR a non-empty interpreter_candidates_by_format
+    // (format genuinely unknown, still TBD by the viewer itself — see
+    // tryInterpreterCandidatesAnyFormat), selects the raw_text+interpreter
+    // path (XML, HTML included, via a host-supplied interpreter script) over the
+    // normal already-parsed-value path (see StructileWidget in widget.py).
+    const rawFormat = model.get("raw_format");
+    const candidatesByFormat = model.get("interpreter_candidates_by_format");
+    const hasCandidatesByFormat = candidatesByFormat && Object.keys(candidatesByFormat).length > 0;
+    const msg = {
+      type: "structile-embed-init",
+      name: model.get("data_name"),
+      config: JSON.parse(model.get("config_json")),
+      // Shows the viewer's settings panel (normally hidden in every embed
+      // host — see enableSettingsPanel in structile.html's EMBEDDED
+      // MODE section) and its "Set as default" button, which posts
+      // structile-settings-changed back — see onViewerMessage below.
+      enableSettingsPanel: true,
+    };
+    if (rawFormat || hasCandidatesByFormat) {
+      msg.text = model.get("raw_text");
+      msg.format = rawFormat;
+      // interpreter_source is a single string or a list of candidates —
+      // the viewer tries each itself (tryInterpreterCandidates), so this
+      // widget never has to disambiguate more than one candidate.
+      const interpreterSource = model.get("interpreter_source");
+      if (hasInterpreterSource(interpreterSource)) msg.interpreterSource = interpreterSource;
+      if (hasCandidatesByFormat) msg.interpreterCandidatesByFormat = candidatesByFormat;
+    } else {
+      msg.text = model.get("value_json");
+      msg.format = "json";
+    }
+    iframe.contentWindow.postMessage(msg, "*");
+  }
+
+  // The viewer's own init() attaches its "message" listener synchronously
+  // during initial script execution, which finishes well before the
+  // iframe's "load" event (DOMContentLoaded, then load) — so it's always
+  // listening by the time this fires.
+  iframe.addEventListener("load", sendInit, { once: true });
+  model.on("change:value_json", sendInit);
+  model.on("change:raw_text", sendInit);
+  model.on("change:raw_format", sendInit);
+  model.on("change:interpreter_source", sendInit);
+  model.on("change:interpreter_candidates_by_format", sendInit);
+  model.on("change:data_name", sendInit);
+  model.on("change:config_json", sendInit);
+
+  // Viewer -> host: dirty-state is plain synced state (a trait, pushed
+  // whenever it changes); save-requested is a one-off event, so it goes
+  // over the custom-message channel instead (model.send <-> Python's
+  // on_msg) rather than a trait, since "a save just happened" isn't state
+  // that makes sense to read back later.
+  function onViewerMessage(e) {
+    if (e.source !== iframe.contentWindow || !e.data) return;
+    const msg = e.data;
+    if (msg.type === "structile-dirty-state-changed") {
+      model.set("dirty", !!msg.dirty);
+      model.set("dirty_count", msg.totalCount || 0);
+      model.save_changes();
+    } else if (msg.type === "structile-save-requested") {
+      forwardSaveRequested(model, msg);
+    } else if (msg.type === "structile-settings-changed") {
+      forwardSettingsChanged(model, msg);
+    }
+  }
+  window.addEventListener("message", onViewerMessage);
+  return () => window.removeEventListener("message", onViewerMessage);
+}
+
+function renderDiff(model, iframe) {
+  function sendInit() {
+    if (!iframe.contentWindow) return;
+    const msg = {
+      type: "structile-embed-diff-init",
+      left: { text: model.get("left_text"), format: model.get("left_format"), name: model.get("left_name") },
+      right: { text: model.get("right_text"), format: model.get("right_format"), name: model.get("right_name") },
+      config: JSON.parse(model.get("config_json")),
+      diff: { view: model.get("diff_view") },
+    };
+    const keyColumns = model.get("key_columns");
+    if (keyColumns && keyColumns.length) msg.keyColumns = keyColumns;
+    const leftInterp = model.get("left_interpreter_source");
+    if (hasInterpreterSource(leftInterp)) msg.leftInterpreterSource = leftInterp;
+    const rightInterp = model.get("right_interpreter_source");
+    if (hasInterpreterSource(rightInterp)) msg.rightInterpreterSource = rightInterp;
+    iframe.contentWindow.postMessage(msg, "*");
+  }
+
+  iframe.addEventListener("load", sendInit, { once: true });
+  model.on("change:left_text", sendInit);
+  model.on("change:left_format", sendInit);
+  model.on("change:left_name", sendInit);
+  model.on("change:right_text", sendInit);
+  model.on("change:right_format", sendInit);
+  model.on("change:right_name", sendInit);
+  model.on("change:left_interpreter_source", sendInit);
+  model.on("change:right_interpreter_source", sendInit);
+  model.on("change:diff_view", sendInit);
+  model.on("change:key_columns", sendInit);
+  model.on("change:config_json", sendInit);
+
+  // No dirty-state-changed for diff mode (the viewer never emits one — see
+  // structile.html's emitDirtyStateChanged, single-value-only) —
+  // only a per-side structile-save-requested (with `side`), forwarded the same
+  // way the value widget forwards its own.
+  function onViewerMessage(e) {
+    if (e.source !== iframe.contentWindow || !e.data) return;
+    const msg = e.data;
+    if (msg.type === "structile-save-requested") {
+      forwardSaveRequested(model, msg, { side: msg.side });
+    }
+  }
+  window.addEventListener("message", onViewerMessage);
+  return () => window.removeEventListener("message", onViewerMessage);
+}
+
+export default { render };

structile/widget.py

@@ -0,0 +1,406 @@
+"""anywidget front-end wrapper around structile.html (embedded mode)."""
+from __future__ import annotations
+
+import json
+import pathlib
+from typing import TYPE_CHECKING, Any, Callable, Dict, List, Optional, Union
+
+import anywidget
+import traitlets
+
+from ._log import logger
+from ._paths import find_viewer_html as _find_viewer_html
+from .config import options_from_dict, replace_options
+from .serialize import normalize
+
+if TYPE_CHECKING:
+    from .render import Payload
+
+_PACKAGE_DIR = pathlib.Path(__file__).resolve().parent
+
+
+class StructileWidget(anywidget.AnyWidget):
+    """Renders structile.html, in embedded mode, inside an iframe.
+
+    The value is handed to the viewer over its existing host<->viewer
+    postMessage protocol (see the "EMBEDDED MODE" section of
+    structile.html) — this class never reaches into the viewer's
+    internals, it only speaks that protocol from the JS side (see
+    static/widget.js).
+
+    Two data paths, matching `structile-embed-init`'s own `value` vs `text`+
+    `format` split:
+      - `value_json` (the default): an already-normalized Python value,
+        shown/edited/saved as JSON.
+      - `raw_text` + `raw_format` ("xml"/"html", or any other format like
+        "ini") + `interpreter_source`: raw source text run through a
+        host-supplied interpreter script, for data `normalize()` has no
+        business touching. `interpreter_source` is a single source or a
+        list of candidates — the viewer tries each itself
+        (structile.html's `tryInterpreterCandidates`), so
+        disambiguating more than one never needs Node.js here either. When
+        `raw_format` is left `""` (format genuinely unknown), the viewer
+        instead tries every entry of `interpreter_candidates_by_format`
+        (`{"xml": [...], "ini": [...]}` — any mix of formats) to determine
+        the format itself.
+
+    Edits made in the viewer come back on save (Ctrl+S / Save),
+    via `structile-save-requested` — never live per-keystroke, matching the
+    viewer's own "nothing but Save commits an edit" contract. `self.value`
+    is updated in place; if a target path is known (`source_path` or an
+    explicit `save_path`), that file is written too — Python, not the
+    browser, owns the filesystem in embedded mode.
+
+    The viewer's Save As… button (embed-only — see `[data-embed-only]` in
+    structile.html) sends the same message with a new `fileName`,
+    which `_resolve_save_path` honors as a rename: the new file is written
+    *alongside* `source_path` (never overwriting it) and adopted as
+    `self._source_path` for every save after that, so there's no lingering
+    "which file is this, really" ambiguity — what's on screen and what the
+    next Save writes to always agree. A rename that would silently clobber
+    an unrelated, already-existing file is refused instead (see
+    `_handle_save`), since there's no channel back to the viewer to ask
+    "overwrite?" first.
+
+    `self.source_text` tracks the literal text of the most recent save (or
+    the initial load) even when it doesn't parse — the viewer's source pane
+    (source_code_view_claude.md) can save a mid-edit/invalid buffer on
+    purpose (its own "Save source (graph is stale)" case), and that literal
+    text is still written to disk. `self.value` never reflects that broken
+    intermediate state — it only ever updates on a SUCCESSFUL parse, so
+    anything reading `.value` between saves never sees a broken one.
+    """
+
+    _esm = _PACKAGE_DIR / "static" / "widget.js"
+
+    # Shared with StructileDiffWidget's own "diff" — static/widget.js's
+    # render() branches on this to decide which embed-init message (single-
+    # value vs two-sided) to send, since both classes point at the same ESM
+    # file.
+    mode = traitlets.Unicode("value").tag(sync=True)
+    value_json = traitlets.Unicode("null").tag(sync=True)
+    raw_text = traitlets.Unicode("").tag(sync=True)
+    raw_format = traitlets.Unicode("").tag(sync=True)
+    # A single source, or a list of candidates the viewer tries itself —
+    # see the class docstring. traitlets.Union tries each trait in order,
+    # same as the plain-string case has always worked.
+    interpreter_source = traitlets.Union(
+        [traitlets.Unicode(), traitlets.List(traitlets.Unicode())], default_value=""
+    ).tag(sync=True)
+    # {"xml": [...], "ini": [...]} — any mix of formats — only used when raw_format is "".
+    interpreter_candidates_by_format = traitlets.Dict().tag(sync=True)
+    data_name = traitlets.Unicode("data").tag(sync=True)
+    viewer_html = traitlets.Unicode("").tag(sync=True)
+    height = traitlets.Int(600).tag(sync=True)
+    # JSON-encoded embedded-mode `config` object (settings/theme), or the
+    # literal string "null" for none — see `structile-embed-init` in
+    # structile.html's EMBEDDED MODE section.
+    config_json = traitlets.Unicode("null").tag(sync=True)
+    # Pushed from the viewer on every `structile-dirty-state-changed`.
+    dirty = traitlets.Bool(False).tag(sync=True)
+    dirty_count = traitlets.Int(0).tag(sync=True)
+
+    def __init__(
+        self,
+        *,
+        value_json: str = "null",
+        raw_text: str = "",
+        raw_format: str = "",
+        interpreter_source: Union[str, List[str]] = "",
+        interpreter_candidates_by_format: Optional[Dict[str, List[str]]] = None,
+        data_name: str = "data",
+        height: int = 600,
+        config_json: str = "null",
+        value: Any = None,
+        source_path: Optional[pathlib.Path] = None,
+        save_path: Optional[pathlib.Path] = None,
+        **kwargs: Any,
+    ) -> None:
+        # Read fresh on every construction (not once at import time) so
+        # local edits to structile.html show up in the next
+        # open(...) call without reinstalling the package.
+        viewer_html = _find_viewer_html().read_text(encoding="utf-8")
+        super().__init__(
+            value_json=value_json,
+            raw_text=raw_text,
+            raw_format=raw_format,
+            interpreter_source=interpreter_source,
+            interpreter_candidates_by_format=interpreter_candidates_by_format or {},
+            data_name=data_name,
+            height=height,
+            config_json=config_json,
+            viewer_html=viewer_html,
+            **kwargs,
+        )
+        # Plain instance state, not a synced trait — Python-only, mirrors
+        # whatever was last shown/saved rather than something the JS side
+        # reads or drives.
+        self.value = value
+        # The literal text of the most recent save (or the initial load),
+        # regardless of whether it parsed — see _handle_save. Separate from
+        # .value, which only ever reflects the last SUCCESSFULLY parsed
+        # value (source_code_view_claude.md Phase 6's ".value"/raw-text
+        # distinction for invalid-buffer saves).
+        self.source_text = raw_text or value_json
+        self._source_path = source_path
+        self._save_path = save_path
+        self.on_msg(self._on_custom_msg)
+
+    def set_value(self, obj: Any, *, name: Optional[str] = None, default: Optional[Callable[[Any], Any]] = None) -> None:
+        """Replace the displayed value in place (re-renders the viewer).
+
+        `default`: same `normalize()` escape hatch as `open()`'s own
+        `default=` — called on any value `normalize()` doesn't otherwise
+        support, in place of raising `TypeError`.
+        """
+        normalized = normalize(obj, default)
+        self.raw_format = ""
+        self.value_json = json.dumps(normalized, indent=2)
+        self.value = normalized
+        self.source_text = self.value_json
+        if name is not None:
+            self.data_name = name
+
+    # NOT named _handle_msg — ipywidgets.Widget already defines a method by
+    # that exact name (the real comm-message router, wired to the comm via
+    # on_msg during open(): handles state "update" — the sync a plain
+    # model.set()+save_changes() in JS produces, e.g. dirty/dirty_count —
+    # AND dispatches "custom" messages, e.g. our own model.send(...), to
+    # on_msg-registered callbacks like this one). Reusing that name here
+    # would silently override it instead of adding to it, breaking both.
+    def _on_custom_msg(self, widget: "StructileWidget", content: Any, buffers: Any) -> None:
+        if not isinstance(content, dict):
+            return
+        if content.get("type") == "structile-save-requested":
+            logger.debug("structile: widget received structile-save-requested")
+            self._handle_save(content)
+        elif content.get("type") == "structile-settings-changed":
+            logger.debug("structile: widget received structile-settings-changed")
+            self._handle_settings_changed(content)
+
+    def _handle_save(self, content: dict) -> None:
+        text = content.get("content")
+        if not isinstance(text, str):
+            logger.warning("structile: structile-save-requested had no usable content, ignoring (%r)", content.get("error"))
+            return
+        self.source_text = text  # the literal buffer, saved as-is below regardless of validity
+        if self.raw_format:
+            self.value = text  # xml/html/etc — already serialized text, nothing to parse
+        else:
+            try:
+                self.value = json.loads(text)
+            except ValueError:
+                # Mid-edit/invalid JSON — source_code_view_claude.md Phase
+                # 3b's "Save source (graph is stale)" case, saveable on
+                # purpose. .value keeps reflecting the last successfully
+                # parsed value (so anything reading it between saves never
+                # sees a broken parse) rather than becoming the raw,
+                # unparseable text itself; the literal buffer is still
+                # captured above (self.source_text) and still written to
+                # disk below.
+                logger.debug("structile: structile-save-requested content isn't valid JSON, .value left unchanged")
+        target = self._resolve_save_path(content)
+        if target is None:
+            logger.debug("structile: save updated self.value only (no source_path/save_path known)")
+            return
+        if target != self._source_path and target.exists():
+            # Save As colliding with an existing, unrelated file — refuse
+            # rather than silently clobbering it. There's no ack/error
+            # channel back to the viewer for this message (see
+            # structile-save-requested in the "EMBEDDED MODE" protocol doc), so the
+            # only signal is this log line; self.value/self.source_text above
+            # already reflect the saved buffer either way, and a plain Save
+            # right after this still targets the ORIGINAL file, unaffected by
+            # the rejected rename (self._source_path is left untouched).
+            logger.warning(
+                "structile: save-as target %s already exists, refusing to overwrite it — data kept in-memory only",
+                target,
+            )
+            return
+        target.write_text(text, encoding="utf-8")
+        self._source_path = target
+        logger.info("structile: saved %s", target)
+
+    def _resolve_save_path(self, content: dict) -> Optional[pathlib.Path]:
+        """Where to write on save: a caller-fixed `save_path` always wins;
+        otherwise the file this data was loaded from. `fileName` normally just
+        equals that file's stem (an ordinary Save/Ctrl+S), but a differing one
+        — from the viewer's own embed-only Save As… popover (performSaveAs in
+        structile.html), or some other future host mechanism — is
+        honored as a rename: written alongside the original (which is never
+        itself touched) and adopted as `self._source_path` for every save
+        after this one (see _handle_save). `None` (no known path — an
+        in-memory object with no `path=` override) means: update `self.value`
+        only and write nothing — deliberately true for Save As too, since
+        without an existing source_path there's no directory to anchor a new
+        file's location to."""
+        if self._save_path is not None:
+            return self._save_path
+        if self._source_path is None:
+            return None
+        file_name = content.get("fileName")
+        ext = content.get("ext") or self._source_path.suffix.lstrip(".")
+        if file_name and file_name != self._source_path.stem:
+            try:
+                return self._source_path.with_name(file_name + "." + ext)
+            except ValueError:
+                # An invalid name (e.g. containing a path separator) reached
+                # here despite the viewer's own inline validation
+                # (sanitizeSaveAsName in structile.html) — some other
+                # protocol producer, or a stale cached build. Fall back to the
+                # current path rather than raising out of a comm message
+                # handler.
+                logger.warning("structile: ignoring invalid save-as file name %r", file_name)
+                return self._source_path
+        return self._source_path
+
+    def _handle_settings_changed(self, content: dict) -> None:
+        """The viewer's embed-only "Set as default" button (see
+        enableSettingsPanel/structile-settings-changed in structile.html's
+        EMBEDDED MODE section) — `content` is the FULL current settings-panel
+        state (settings/renderMap/links/theme), not a diff, same as Export
+        Settings would produce. Promotes it into `structile.options`
+        (matplotlib.rcParams-style — see config.replace_options), so it
+        becomes the new baseline for every `open()` call for the rest
+        of this process. This widget instance itself is unaffected — it
+        already shows these values."""
+        payload = dict(content.get("settings") or {})
+        payload.update(content.get("renderMap") or {})
+        # `links` carries the viewer's own {open, close} field names (see
+        # structile.html's linkSettings) — renamed to the
+        # Python-facing linkOpen/linkClose option names (see
+        # config._LINK_KEYS_TO_FIELD for the reverse direction).
+        links = content.get("links") or {}
+        if "open" in links:
+            payload["linkOpen"] = links["open"]
+        if "close" in links:
+            payload["linkClose"] = links["close"]
+        if "theme" in content:
+            payload["theme"] = content["theme"]
+        try:
+            opts = options_from_dict(payload)
+        except (AttributeError, TypeError, ValueError) as e:
+            logger.warning("structile: structile-settings-changed had an invalid payload, ignoring (%s)", e)
+            return
+        replace_options(opts)
+        logger.info("structile: settings panel state promoted to structile.options (module default)")
+
+
+class StructileDiffWidget(anywidget.AnyWidget):
+    """Renders structile.html in embedded two-sided diff mode
+    (`structile-embed-diff-init` — see the "EMBEDDED MODE"/"DIFF MODE" sections of
+    structile.html), for `structile.diff(renderer="widget")`.
+
+    Shares `static/widget.js` with `StructileWidget` (its `mode` trait is
+    what tells the front end which embed-init message to build/send) rather
+    than duplicating the iframe-mounting boilerplate for a second file.
+
+    The diff graph itself is always read-only (same as every other diff
+    renderer), but each side's own source pane is independently editable and
+    saveable — see structile.html's `performDiffSideSave`, which
+    posts `structile-save-requested` with a `side: "left" | "right"` field. Saving
+    a side updates `self.left_value`/`self.right_value` in place; there is
+    no `left_path`/`right_path` to write back to yet (`structile.diff()`
+    doesn't take one), so — mirroring `StructileWidget`'s own "no
+    source_path/save_path known" case — a save only ever updates the
+    in-memory value, never a file.
+    """
+
+    _esm = _PACKAGE_DIR / "static" / "widget.js"
+
+    mode = traitlets.Unicode("diff").tag(sync=True)
+    left_text = traitlets.Unicode("").tag(sync=True)
+    left_format = traitlets.Unicode("").tag(sync=True)
+    left_name = traitlets.Unicode("left").tag(sync=True)
+    right_text = traitlets.Unicode("").tag(sync=True)
+    right_format = traitlets.Unicode("").tag(sync=True)
+    right_name = traitlets.Unicode("right").tag(sync=True)
+    # Same Union-of-str-or-list shape as StructileWidget.interpreter_source,
+    # once per side (a diff's two sides can be different, mutually
+    # incompatible markup schemas — see structile.diff()'s own
+    # interpreter=/format= docs).
+    left_interpreter_source = traitlets.Union(
+        [traitlets.Unicode(), traitlets.List(traitlets.Unicode())], default_value=""
+    ).tag(sync=True)
+    right_interpreter_source = traitlets.Union(
+        [traitlets.Unicode(), traitlets.List(traitlets.Unicode())], default_value=""
+    ).tag(sync=True)
+    diff_view = traitlets.Unicode("unified").tag(sync=True)
+    key_columns = traitlets.List(traitlets.Unicode()).tag(sync=True)
+    viewer_html = traitlets.Unicode("").tag(sync=True)
+    height = traitlets.Int(600).tag(sync=True)
+    config_json = traitlets.Unicode("null").tag(sync=True)
+
+    def __init__(
+        self,
+        *,
+        left: "Payload",
+        right: "Payload",
+        view: str = "unified",
+        key_columns: Optional[list] = None,
+        height: int = 600,
+        **kwargs: Any,
+    ) -> None:
+        viewer_html = _find_viewer_html().read_text(encoding="utf-8")
+        config_json = json.dumps(left.config) if left.config is not None else "null"
+        super().__init__(
+            left_text=left.text,
+            left_format=left.format,
+            left_name=left.name,
+            right_text=right.text,
+            right_format=right.format,
+            right_name=right.name,
+            left_interpreter_source=left.interpreter_source or "",
+            right_interpreter_source=right.interpreter_source or "",
+            diff_view=view if view == "split" else "unified",
+            key_columns=list(key_columns or []),
+            viewer_html=viewer_html,
+            height=height,
+            config_json=config_json,
+            **kwargs,
+        )
+        # Plain instance state (not synced traits) — mirrors StructileWidget's
+        # own .value: Python-only, updated on each side's own Save. Parsed
+        # up front for a "json" side (matching open()'s own
+        # already-normalized initial .value) — every other format (no
+        # Python-side parser here — see _handle_save) keeps the raw text.
+        self.left_value: Any = json.loads(left.text) if left.format == "json" else left.text
+        self.right_value: Any = json.loads(right.text) if right.format == "json" else right.text
+        self.on_msg(self._on_custom_msg)
+
+    def _on_custom_msg(self, widget: "StructileDiffWidget", content: Any, buffers: Any) -> None:
+        if isinstance(content, dict) and content.get("type") == "structile-save-requested":
+            logger.debug("structile.diff: widget received structile-save-requested")
+            self._handle_save(content)
+
+    def _handle_save(self, content: dict) -> None:
+        text = content.get("content")
+        side = content.get("side")
+        if not isinstance(text, str) or side not in ("left", "right"):
+            logger.warning(
+                "structile.diff: widget structile-save-requested had no usable content/side, ignoring (%r)",
+                content.get("error"),
+            )
+            return
+        # Unlike StructileWidget.raw_format (only truthy for markup/other
+        # non-JSON formats — "" means "plain JSON value"), a diff side's own
+        # `format` is always a real string, "json" included (see
+        # _resolve_diff_side) — so the "already-serialized, nothing to
+        # parse" check has to name "json" explicitly rather than testing
+        # for emptiness. "python" text has no Python-side repr parser here
+        # (same gap `_describe_payload_for_text` already has), so it's kept
+        # as raw text too, same as xml/html/any other format.
+        fmt = self.left_format if side == "left" else self.right_format
+        if fmt == "json":
+            try:
+                value: Any = json.loads(text)
+            except ValueError:
+                logger.debug("structile.diff: %s side saved non-JSON text, value left unchanged", side)
+                return
+        else:
+            value = text
+        if side == "left":
+            self.left_value = value
+        else:
+            self.right_value = value
+        logger.info("structile.diff: %s side saved (in-memory only — diff() has no source path to write back to)", side)