meltygui 0.1.0__py3-none-any.whl

meltygui/code/live_view.py

@@ -0,0 +1,2490 @@
+"""live_view() — capture a running local and key it by its CST-dict address.
+
+User code drops a bare `live_view()` after an assignment (or `live_view(expr)`
+anywhere) in a function body. At runtime the call resolves its own site to the
+SAME key the libcst→dict conversion gives that statement — `("if##0",
+"live_view()")`, not a line number — reads the preceding local for the bare
+form, and stores the value RAW on the OWNING FUNCTION object under
+`__live_values__`. The editor reads the store off the object it is editing
+(`live_values_for`) and renders each value as a nested window anchored to the
+call's inline token, so the value and the code that produced it stay linked.
+
+Why CST keys, not line numbers: the keys (`x`, `x#1`, `live_view()#N`,
+`if##0`) are structural — they survive the line drift between code that is
+RUNNING (an old frame in a training loop) and source that is being edited.
+Keys are relative to the STORE OBJECT's scope (the segments after the owning
+def's own "locals"), so a nested def's sites stay distinct on the outer
+function they attach to, and the editor's span parse sees the same paths.
+Statements the dict conversion doesn't surface (while/with/match bodies,
+nested defs) fall back to a `line:N`-qualified key — still distinct per site,
+just line-stable instead of edit-stable.
+
+Why the function object: hotswap mutates `func.__code__` in place
+(file_converters._recompile) and never rebinds the module var, so the function
+object — and this store — keeps its identity across recompiles. The capture
+side and the editor side converge on the same object through the same
+resolver (`_enclosing_function`). Class-body and module-level sites attach to
+the module instead (a class-body frame is not CO_OPTIMIZED — see
+_resolve_site).
+
+Two parses, both bounded: a C-speed `ast` parse of the file finds the
+enclosing top-level statement and the bare form's preceding assignment (ast
+sees aug-assigns, tuple unpacks, while/with bodies — everything the display
+dict elides), then the libcst→dict pass runs on JUST that statement's span, so
+a save of a large file costs O(function), not the whole-file position pass
+that chain_converters measured at ~1s of GIL stall.
+
+Capture must be hot-loop cheap: everything line-dependent is resolved ONCE per
+(code object, line) and cached BY CODE OBJECT IDENTITY — the steady-state path
+is two dict lookups, no stat / parse / sys.modules walk. A hotswap installs a
+new code object, whose first live_view call re-resolves against the file; the
+old code object's sites evict via weakref.finalize.
+
+Known limit: a frame still executing OLD code after a hotswap-without-save
+reports linenos that may not match the file on disk, so a site first resolved
+after that point can mis-key until the function re-enters. Sites resolved
+before the swap are cached and stay correct.
+
+Loop sites ACCUMULATE: a site enclosed by for/while loops (statically known —
+from the injected snapshot's loop context or the site resolution's own ast
+walk) folds each publish into a per-key accumulator instead of overwriting.
+Tensors/ndarrays append along a new leading dim per enclosing loop, auto-named
+from the loop variable ('l_idx' for `for l_idx, layer in enumerate(…)`);
+everything else appends to a list. See _accumulate for the growth-buffer,
+rollover, and nested-grid mechanics, and __live_dim_names__ /
+auto_dim_names_for for how the editor marker merges the auto names into the
+value window's dim_names.
+"""
+
+import ast
+import inspect
+import itertools
+import sys
+import threading
+import time
+import types
+import weakref
+from contextlib import contextmanager
+from pathlib import Path
+
+_MISSING = object()
+
+# Guards _sites entry creation only. Parses run OUTSIDE any lock - two threads
+# racing a first call may duplicate a parse (benign, identical results) instead
+# of one file's parse blocking every other file's resolution.
+_lock = threading.Lock()
+
+# id(code object) -> {lineno: _Site or None}. Identity-keyed, NOT a
+# WeakKeyDictionary - code objects compare equal across files (co_filename is
+# excluded from code equality), so identity keying aliases same-source
+# functions in different files onto one site. A weakref.finalize evicts the
+# entry when the code object dies - hotswap gives the function a new __code__,
+# the old one's sites evict themselves. (A None site marks a failed
+# resolution, so it never re-parses per call.)
+_sites = {}
+
+# Every object that ever owned a live store (functions, the def-run path's
+# parked twins, ...). Weak: a store owner that dies takes its store with it.
+# The CUDA OOM responder (gc_manager.respond_to_cuda_oom) sweeps these -
+# nothing else enumerates stores, they are found by resolution.
+_store_owners = globals().get("_store_owners")
+if _store_owners is None:
+    _store_owners = weakref.WeakSet()
+
+# str(path) -> (mtime, ast.Module, source text). One C-speed parse per file
+# version, shared by span lookup and previous-assignment resolution.
+_asts = {}
+
+# (str(path), span start line) -> (mtime, LineMap). One libcst→dict pass per
+# top-level statement (def/class) version - function-size, latest mtime wins.
+_linemaps = {}
+
+# (str(path), lineno) -> (sig, (store_obj, key_path)). site_for_line memo -
+# the editor overlay resolves every visible live_view token per repaint, and
+# the chain under it (enclosing-def walk, file parse, linemap) is
+# once-per-edit slow. Keyed on _ast_for's (mtime, pending_edit) sig; negative
+# results cached too (a token with no surfaced site would otherwise re-walk
+# per repaint).
+_site_for_line_cache = {}
+
+
+class _Site:
+    """Everything line-dependent about one live_view call site, resolved once.
+    `key_path` is relative to `store_obj`'s scope; `var_name` labels (and for
+    the bare form, selects) the captured local; `arg_label` is the explicit
+    form's argument source text; `loop_dims` names the enclosing loops
+    (outermost first — see _loop_dims_at), which turns the site's publishes
+    into accumulation instead of overwrite."""
+    __slots__ = ("key_path", "var_name", "arg_label", "store_obj", "lineno",
+                 "loop_dims")
+
+    def __init__(self, key_path, var_name, arg_label, store_obj, lineno,
+                 loop_dims=()):
+        self.key_path = key_path
+        self.var_name = var_name
+        self.arg_label = arg_label
+        self.store_obj = store_obj
+        self.lineno = lineno
+        self.loop_dims = loop_dims
+
+
+def live_view(value=_MISSING, name=None):
+    """Publish a live value for the editor, keyed by this call's CST address.
+
+    Bare form — `live_view()` — captures the variable assigned by the
+    PRECEDING statement (aug-assigns and block bodies included; resolved from
+    the ast, not the display dict). Explicit form — `live_view(expr)` —
+    captures expr and passes it through, so `y = live_view(f(x))` works
+    inline. A site inside a loop ACCUMULATES instead of overwriting — see
+    _accumulate; the loop variables' current values are read from the calling
+    frame so int-indexed loops key entries by iteration. Never raises into
+    the caller; an unresolvable site is recorded once and skipped
+    thereafter."""
+    frame = sys._getframe(1)
+    try:
+        site = _site_for(frame.f_code, frame.f_lineno)
+        if site is None or site.store_obj is None:
+            return None if value is _MISSING else value
+        bare = value is _MISSING
+        if bare:
+            if site.var_name is None:
+                return None
+            resolved = frame.f_locals.get(site.var_name, _MISSING)
+            if resolved is _MISSING:
+                return None
+        else:
+            resolved = value
+        dims = getattr(site, "loop_dims", ()) or None
+        idx = (tuple(frame.f_locals.get(d) for d in dims)
+               if dims else None)
+        _publish(site, resolved, name, bare, dims=dims, idx=idx)
+        return resolved
+    finally:
+        del frame
+
+
+def twin_snap(value, name=None, dims=None):
+    """The instrumented twin's injected snapshot hook (`__lv_view__`) — the
+    FAST publish path. Synthesizes the same ``line:N#name`` keys the
+    frame-snapshot publisher uses (the overlay anchors line keys by line and
+    boxes by label), so a twin run does NO site resolution: the classic path
+    pays a libcst linemap per enclosing span (~240ms for a big function,
+    the whole CLASS for a method) on every fresh twin code object — i.e.
+    after every edit. Store resolution is the cached _enclosing_function
+    walk. Sharing the frame-snapshot key scheme also means a twin run and a
+    context-menu snapshot UPDATE THE SAME MARKERS instead of doubling them.
+    Manual live_view() calls in the body keep the structural-key path (their
+    markers anchor to the call token). Falls back to the classic resolved
+    path when the store can't be resolved.
+
+    `dims` is the instrumentation's STATIC loop context — the names of the
+    loops enclosing the snapped assignment, outermost first (see
+    live_instrument._inject_snaps). When present, the loop variables' current
+    values are read from the twin frame and the publish ACCUMULATES (stacked
+    tensors / lists) instead of overwriting — see _accumulate."""
+    frame = sys._getframe(1)
+    try:
+        code, lineno = frame.f_code, frame.f_lineno
+        idx = (tuple(frame.f_locals.get(d) for d in dims)
+               if dims else None)
+    finally:
+        del frame
+    dims = tuple(dims) if dims else None
+    try:
+        # The run's own store comes first (run_capture on this file, same
+        # file): the prune at run end and the accumulator's fresh-run reset
+        # both key on that object, so publishing anywhere else leaks.
+        fn = current_run_owner()
+        try:
+            same_file = (fn is not None and isinstance(fn, types.FunctionType)
+                         and fn.__code__.co_filename == code.co_filename)
+        except Exception:
+            same_file = False
+        if not same_file:
+            from meltygui.code.chain_converters import _enclosing_function
+            fn = _enclosing_function(code.co_filename, lineno)
+        if (isinstance(fn, types.FunctionType)
+                and isinstance(name, str) and name.isidentifier()):
+            site = _Site((f"line:{lineno}#{name}",), None, None, fn, lineno)
+            _publish(site, value, name, bare=False, dims=dims, idx=idx)
+            return value
+    except Exception:
+        pass
+    site = _site_for(code, lineno)
+    if site is not None and site.store_obj is not None:
+        _publish(site, value, name, bare=False, dims=dims, idx=idx)
+    return value
+
+
+def twin_ret(value=None):
+    """The instrumented twin's return hook (`__lv_ret__`): every `return X`
+    in the twin compiles as `return __lv_ret__(X)` (bare `return` passes
+    None), so the calling frame's f_lineno IS the return statement's
+    original file line. Stamps `__live_return_line__` ((absolute 1-indexed
+    file line, run-time line text)) on the resolved store function and wakes the store-level
+    watchers, so the editor's snapshot overlay can wash that line green —
+    the success twin of the red error-line wash — the moment the run comes
+    out. run_instrumented clears the stamp at run start, so a raise (or an
+    edit that removes the return) never leaves a stale green line. Returns
+    the value unchanged."""
+    frame = sys._getframe(1)
+    try:
+        code, lineno = frame.f_code, frame.f_lineno
+    finally:
+        del frame
+    try:
+        from meltygui.code.chain_converters import _enclosing_function
+        fn = _enclosing_function(code.co_filename, lineno)
+        if isinstance(fn, types.FunctionType):
+            stamp_run_marker(fn, "__live_return_line__",
+                             (lineno, _line_text_at(fn, lineno)))
+    except Exception:
+        pass
+    return value
+
+
+def _line_text_at(fn, lineno):
+    """The run-time text of absolute file line `lineno` in fn's file — read
+    from the same cached in-memory build the twin compiles against (disk +
+    pending splices, via _ast_for), so it costs a dict hit per run. Stamped
+    alongside the exit-line numbers so the overlay can re-find the line by
+    CONTENT after later edits shift it — the wash follows its statement the
+    way line-keyed markers follow their symbols. Never raises; None when
+    unresolvable."""
+    try:
+        path = Path(inspect.unwrap(fn).__code__.co_filename).resolve()
+        _tree, text, _sig = _ast_for(path, path.stat().st_mtime)
+        lines = text.split("\n")
+        if 1 <= lineno <= len(lines):
+            return lines[lineno - 1]
+    except Exception:
+        pass
+    return None
+
+
+def stamp_run_marker(fn, attr, value):
+    """Stamp a per-run marker attribute (`__live_return_line__`,
+    `__live_error_line__`) on a store function and wake its store-level
+    watchers (the snapshot editors) with the same throttled render wake the
+    publish path uses, so the editor washes appear without an unrelated
+    repaint. Safe from any thread; swallows everything — markers are
+    decoration, never worth breaking a run over."""
+    try:
+        vars(fn)[attr] = value
+        notified = False
+        try:
+            targets = tuple(
+                getattr(fn, "__live_store_watchers__", None) or ())
+        except RuntimeError:
+            targets = ()
+        for ds in targets:
+            try:
+                ds.invalidate()
+                notified = True
+            except Exception:
+                pass
+        if notified:
+            global _last_wake
+            now = time.time()
+            if now - _last_wake > 0.033:
+                _last_wake = now
+                from meltygui.core.windowing.glfw_utils import request_render
+                request_render()
+    except Exception:
+        pass
+
+
+def call_with_body_capture(func, kwargs, on_captured=None):
+    """Call ``func(**kwargs)`` and capture its body frame's locals at return,
+    handing them to the async frame-snapshot publisher.
+
+    This is the context menu's one-shot answer to "what are the TARGET's
+    mid-body locals": the wrapper's stack capture runs before the body
+    executes, so entry kwargs were all it could publish and the func tab
+    showed markers only on the signature. A per-thread profile hook watches
+    for the target code's outermost 'return' (depth-tracked, so a
+    self-recursive view captures the WIDGET's frame, not an inner one);
+    profiling covers only this one call's subtree, armed on menu-open only —
+    never steady-state. An exception unwind still fires the profile return
+    event, so a crashed body publishes its state at the raise."""
+    inner = inspect.unwrap(func)
+    target_code = getattr(inner, "__code__", None)
+    if target_code is None:
+        return func(**kwargs)
+    captured = {}
+    exit_line = [None]
+    depth = [0]
+
+    def _finish():
+        if captured:
+            # The GLOBAL half (return-line wash + frame-snapshot publish)
+            # stays behind the live-view toggle, exactly as before. The
+            # LOCAL half - `on_captured` (the context menu's CodeEditor
+            # adopting the body locals into its own stack copy) - always
+            # fires; it touches nothing global.
+            from meltygui.core.runtime.toggles import Toggles
+            if Toggles.TextEditor.enable_live_view:
+                if exit_line[0] is not None:
+                    stamp_run_marker(inner, "__live_return_line__",
+                                     (exit_line[0],
+                                      _line_text_at(inner, exit_line[0])))
+                publish_stack_locals((), extra_snapshots=[(inner, captured,
+                                                           None)])
+            if on_captured is not None:
+                try:
+                    on_captured(dict(captured))
+                except Exception:
+                    pass
+
+    # sys.monitoring with LOCAL events on just the target code object: the
+    # old sys.setprofile hook fired a Python callback for EVERY call/return
+    # in the whole call subtree, running a big view took under  took
+    # SECONDS per capture (the 12s editor frames when the context menu's
+    # capture re-ran draw_text). Local events instrument only target_code,
+    # so the subtree runs at full speed and only pay one callback per
+    # entry/exit of the target itself.
+    def _grab(offset_frames):
+        try:
+            f = sys._getframe(offset_frames)
+            if f.f_code is target_code:
+                captured.update(f.f_locals)
+                # The frame's line AT the callback is the return statement
+                # itself (or the raise, on unwind) - the same
+                # __live_return_line__ the instrumented twin stamps.
+                exit_line[0] = f.f_lineno
+        except Exception:
+            pass
+
+    mon = getattr(sys, "monitoring", None)
+    if mon is not None:
+        try:
+            mon.use_tool_id(mon.PROFILER_ID, "lsd-live-capture")
+        except Exception:
+            mon = None   # tool slot busy - fall back to setprofile
+    if mon is not None:
+        def _on_start(code, off):
+            depth[0] += 1
+
+        def _on_return(code, off, retval):
+            depth[0] -= 1
+            if depth[0] <= 0 and not captured:
+                _grab(2)   # callback ← returning target frame
+
+        # PY_UNWIND cannot be local to a code object (only PY_START/PY_RETURN
+        # are local-able events — 0x1005 is rejected), so an exception unwind
+        # publishes nothing here. That loses the old profile hook's
+        # capture-at-raise, which is acceptable: the instrumented-twin path
+        # stamps raise lines through its own machinery, and a crashed body
+        # capture just stays un-published.
+        try:
+            ev = mon.events
+            mon.register_callback(mon.PROFILER_ID, ev.PY_START, _on_start)
+            mon.register_callback(mon.PROFILER_ID, ev.PY_RETURN, _on_return)
+            mon.set_local_events(mon.PROFILER_ID, target_code,
+                                 ev.PY_START | ev.PY_RETURN)
+            return func(**kwargs)
+        finally:
+            try:
+                mon.set_local_events(mon.PROFILER_ID, target_code, 0)
+                for _e in (mon.events.PY_START, mon.events.PY_RETURN):
+                    mon.register_callback(mon.PROFILER_ID, _e, None)
+                mon.free_tool_id(mon.PROFILER_ID)
+            except Exception:
+                pass
+            _finish()
+
+    # Monitoring unavailable (tool id busy, e.g. a debugger owns it): return
+    # plainly rather than fall back to the old whole-subtree sys.setprofile
+    # hook, which cost SECONDS for a big view body. The capture (and its
+    # return-line wash) just doesn't happen for this call.
+    return func(**kwargs)
+
+
+def live_values_for(obj):
+    """A SNAPSHOT {key_path: value} of a function/module's store, or {}. The
+    store holds the captured values RAW — no record wrapper — so a reader
+    hands them straight to draw_any and the framework routes by type. Copied
+    so a render-thread iteration can't race a training-thread insert. Looks
+    through decorator wrappers — capture attaches to the UNWRAPPED function,
+    the object whose __code__ hotswap mutates."""
+    try:
+        obj = inspect.unwrap(obj)
+    except Exception:
+        pass
+    store = getattr(obj, "__live_values__", None)
+    return dict(store) if store else {}
+
+
+def label_for(obj, key_path):
+    """The display label published for a key (the explicit name= kwarg, else
+    the variable the bare form read, else the argument's source text), or
+    None. Labels ride the store object beside the values (the same
+    attach-to-object pattern as the watcher sets)."""
+    try:
+        obj = inspect.unwrap(obj)
+    except Exception:
+        pass
+    labels = getattr(obj, "__live_labels__", None)
+    return labels.get(key_path) if labels else None
+
+
+def site_for_line(filename, lineno):
+    """(store_obj, key_path) of the live_view call at a 1-indexed absolute
+    file line — the EDITOR-side mirror of capture resolution. Same caches,
+    same span parse, same relativization, so the widget anchoring a value and
+    the publisher writing it converge on one key by construction. (None, None)
+    when no live_view call is surfaced at that line — e.g. while/with bodies,
+    whose line-keyed fallback sites have no token node to anchor anyway.
+
+    Memoized per (path, line) against _ast_for's (mtime, pending-gen)
+    signature: the editor overlay calls this for every visible live_view
+    token on every repaint, and the resolver chain behind it (realpath,
+    enclosing-def walk, span parse, linemap) is once-per-edit work, not
+    per-frame work."""
+    from meltygui.code.chain_converters import _enclosing_function
+    from meltygui.code.chain_converters import _module_for_file
+    try:
+        path = Path(filename).resolve()
+        mtime = path.stat().st_mtime
+        tree, text, sig = _ast_for(path, mtime)
+        _sck = (str(path), lineno)
+        _sch = _site_for_line_cache.get(_sck)
+        if _sch is not None and _sch[0] == sig:
+            return _sch[1]
+        # Same stamp to line bridge as _resolve_site, anchored at the
+        # enclosing def's disk start when one resolves (module-level stamps
+        # anchor at the stamp - no own-span growth to mis-count there).
+        _fn = _enclosing_function(str(path), lineno)
+        _fc = getattr(_fn, "__code__", None)
+        line_p = lineno + _stamp_delta(
+            path, _fc.co_firstlineno if _fc is not None else lineno)
+        span = _top_level_span(tree, line_p)
+        lm = _linemap_for(path, sig, span, text)
+        ref = _live_view_ref(lm, line_p)
+        if ref is None:
+            _site_for_line_cache[_sck] = (sig, (None, None))
+            return None, None
+        # Function-frame detection, editor flavor: capture reads CO_OPTIMIZED
+        # off the frame; here the parse path crossing a `<name>, "def"`
+        # segment says the call sits in a def body.
+        store_obj = None
+        store_is_module = True
+        if _owning_def_name(ref.path) is not None:
+            store_obj = _fn          # resolved above for the line bridge
+            store_is_module = store_obj is None
+        if store_obj is None:
+            store_obj = _module_for_file(path)
+        if store_obj is None:
+            _site_for_line_cache[_sck] = (sig, (None, None))
+            return None, None
+        key_path = _store_relative(ref.path, store_obj, store_is_module)
+        _res = (store_obj, (key_path or (f"line:{lineno}",)))
+        _site_for_line_cache[_sck] = (sig, _res)
+        return _res
+    except Exception as e:
+        print(f"live_view: site_for_line failed for {filename}:{lineno}: "
+              f"{e!r}", file=sys.stderr)
+        return None, None
+
+
+def install_builtin(name="live_view"):
+    """Make live_view() callable from ANY module with no import — the seamless
+    instrumentation path: type the call, hotswap, run. Mirrors Python's own
+    breakpoint(): a debugging entry point that shouldn't demand source changes
+    beyond the call itself. No-op if the name is already bound to something
+    else in builtins. Also taught to the static lint: code_checks freezes
+    dir(builtins) at ITS import, so patch its set when it loaded first."""
+    import builtins
+    existing = getattr(builtins, name, None)
+    if existing is not None and existing is not live_view:
+        return
+    setattr(builtins, name, live_view)
+    checks = sys.modules.get("meltygui.code.code_checks")
+    if checks is not None and hasattr(checks, "_BUILTIN_NAMES"):
+        checks._BUILTIN_NAMES = frozenset(checks._BUILTIN_NAMES) | {name}
+
+
+def watch(store_obj, key_path, draw_state, first_only=False):
+    """Register a draw_state to invalidate when `key_path` publishes on
+    `store_obj`. Watchers ride the store object (attach-to-object, like the
+    values) in a per-key WeakSet — a closed window's draw_state just drops
+    out. Re-registering every render is the idempotent norm.
+
+    first_only=True fires ONLY on a key's FIRST value: the
+    marker dot registers this way, so a freshly-typed live_view() flips green
+    and auto-opens the moment its code first runs — one editor re-render per
+    new key — without paying a full editor recomposite on every publish.
+
+    key_path=None registers a STORE-LEVEL watcher, fired when ANY brand-new
+    key appears on the object. The snapshot overlay registers the editor this
+    way: before a function's first instrumented run there are no keys, hence
+    no markers, hence no per-key watchers — without this the first run's
+    values would sit invisible until an unrelated editor repaint."""
+    try:
+        if key_path is None:
+            vars(store_obj).setdefault(
+                "__live_store_watchers__", weakref.WeakSet()).add(draw_state)
+            return
+        attr = "__live_first_watchers__" if first_only else "__live_watchers__"
+        watchers = vars(store_obj).setdefault(attr, {})
+        watchers.setdefault(key_path, weakref.WeakSet()).add(draw_state)
+    except (AttributeError, TypeError):
+        pass
+
+
+_PUBLISH_GEN = itertools.count(1)
+
+
+def _stamp_publish_gen(value):
+    """Stamp a monotonic publish generation on a tensor-like value
+    (`_lv_pub`). Views that cache work per source (the voxel / line-graph
+    volume uploads) key on it next to `id()`/`_version`: a fresh run's
+    tensor is routinely allocated at the SAME id as the generation just
+    released at run start (`_release_store_generation` frees it first), and
+    `_version` starts at 0 for both — an identity-only key then hits the
+    cache and shows the previous run's texture. No invalidation involved:
+    the key changes exactly when a new value was published. Values that
+    refuse attributes (ndarrays, scalars) are left alone."""
+    try:
+        if hasattr(value, "shape") and hasattr(value, "__dict__"):
+            value._lv_pub = next(_PUBLISH_GEN)
+    except Exception:
+        pass
+
+
+def publish_gen(value):
+    """The `_lv_pub` stamp of a published value (0 when unstamped) — fold
+    into any per-source cache key beside id()/_version."""
+    try:
+        return int(getattr(value, "_lv_pub", 0) or 0)
+    except Exception:
+        return 0
+
+
+# Largest line distance a re-key may span: an edit shifts a site by the
+# lines it inserted/deleted above it - a same-named assignment further away
+# is a different site.
+REKEY_MAX_SHIFT = 12
+
+
+def bump_keys_gen(store_obj):
+    """Advance the store's KEY-SET generation (`__live_keys_gen__`) — called
+    wherever the set of store keys changes (first publish, re-key, prune).
+    The editor's view-name map is derived from the WHOLE key set (ordinal
+    disambiguation), so every consumer memoizes it on this generation and
+    they all agree within a frame — differently-stale maps minted the same
+    name for different keys (duplicate view IDs)."""
+    try:
+        d = vars(store_obj)
+        d["__live_keys_gen__"] = d.get("__live_keys_gen__", 0) + 1
+    except (AttributeError, TypeError):
+        pass
+
+
+def _adopt_rekeyed(store_obj, key_path, store):
+    """If `key_path` is new to the store while an UNTOUCHED (this run)
+    same-label `line:N#name` key sits within REKEY_MAX_SHIFT lines, that
+    key is this site's previous generation: move its entry — value,
+    accumulator, label, dim names, both watcher sets, frame-snapshot
+    membership — under `key_path`. Nearest line wins; only during an active
+    run (a touched set exists) so a second same-named site is never
+    mistaken for a re-key outside the publish sequence."""
+    if key_path in store:
+        return
+    label = _key_label(key_path)
+    if label is None:
+        return
+    try:
+        d = vars(store_obj)
+    except TypeError:
+        return
+    touched = d.get("__live_touched__")
+    if touched is None:
+        return
+    line = _key_line(key_path)
+    best = None
+    for k in tuple(store):
+        if k in touched or _key_label(k) != label or len(k) != len(key_path):
+            continue
+        kl = _key_line(k)
+        if kl is None or line is None:
+            continue
+        dist = abs(kl - line)
+        if dist > REKEY_MAX_SHIFT or (best is not None and dist >= best[0]):
+            continue
+        best = (dist, k)
+    if best is None:
+        return
+    old = best[1]
+    for attr in ("__live_values__", "__live_accum__", "__live_labels__",
+                 "__live_dim_names__", "__live_watchers__",
+                 "__live_first_watchers__"):
+        m = d.get(attr)
+        if not m or old not in m:
+            continue
+        try:
+            ent = m.pop(old)
+        except (KeyError, RuntimeError):
+            continue
+        if key_path in m and attr in ("__live_watchers__",
+                                      "__live_first_watchers__"):
+            try:
+                m[key_path].update(ent)
+            except Exception:
+                m[key_path] = ent
+        else:
+            m[key_path] = ent
+    snaps = d.get("__frame_snapshot_keys__")
+    if snaps and old in snaps:
+        snaps.discard(old)
+        snaps.add(key_path)
+    bump_keys_gen(store_obj)
+
+
+def _key_line(key_path):
+    """The line of a `line:N#name` key path's last segment, else None."""
+    tail = key_path[-1] if isinstance(key_path, tuple) and key_path else key_path
+    if not isinstance(tail, str) or not tail.startswith("line:"):
+        return None
+    num = tail[5:].partition("#")[0]
+    return int(num) if num.isdigit() else None
+
+
+class RerunHint(str):
+    """The 'Rerun to visualize …' placeholder a released site holds. A str
+    subclass so every existing consumer (the value window's str view, tests)
+    keeps working, while views that treat plain strings specially can tell
+    it apart: the marker's INLINE label refuses it (it's an affordance, not
+    a captured value) and keeps the click/caret popover for it."""
+
+
+def rerun_hint(store_obj, key_path):
+    """The placeholder a loop site holds while nothing shows it."""
+    label = (vars(store_obj).get("__live_labels__") or {}).get(key_path)
+    return RerunHint(f"Rerun to visualize {label or key_path[-1]}")
+
+
+def park_rerun_hint(store_obj, key_path):
+    """A value window just stopped showing: forget its accumulated stack and
+    swap the store value for the rerun hint, then sever every watcher pin
+    (marker + window draw_states, GL texture) so the tensor has no referrer
+    left — the VRAM comes back now, not at the next run. The key STAYS (the
+    marker keeps reading captured); the next run with the window open
+    accumulates again. Any thread; never raises."""
+    try:
+        d = vars(store_obj)
+        accums = d.get("__live_accum__")
+        if accums:
+            accums.pop(key_path, None)
+        store = d.get("__live_values__")
+        if store is not None and key_path in store:
+            store[key_path] = rerun_hint(store_obj, key_path)
+    except (AttributeError, TypeError):
+        return
+    _release_key_watchers(store_obj, key_path)
+
+
+# Headless override for the accumulate-only-when-watched gate below: tests
+# (and any widgetless driver) flip this on so loop sites stack without a
+# window watching them. Patch via unittest.mock / direct assignment.
+ACCUMULATE_UNWATCHED = False
+
+
+def has_visible_widget(store_obj, key_path):
+    """True when some live widget for `key_path` currently SHOWS its value
+    window. The full per-publish watcher (`__live_watchers__`) is registered
+    only while a marker's window exists, but draw_states persist past an
+    X-close, so also require the watcher's window ds to be open. Any
+    thread; never raises."""
+    if ACCUMULATE_UNWATCHED:
+        return True
+    try:
+        watchers = vars(store_obj).get("__live_watchers__")
+        if not watchers:
+            return False
+        try:
+            targets = tuple(watchers.get(key_path) or ())
+        except RuntimeError:  # concurrent registration resized the set
+            return True       # benign, err on the side of accumulating
+        for ds in targets:
+            win = getattr(ds, "_lv_window_ds", None)
+            if win is not None and not getattr(win, "closed", False):
+                return True
+        # Re-keyed site: an edit above the line moved `line:N#name` to
+        # `line:M#name`, and the run publishes the new key before its
+        # (name-keyed, still open) marker has re-rendered and re-watched
+        # it. Nothing is registered under the new key yet, but the window
+        # is right there: treat an open window under any same-named key
+        # as watching (two same-named sites may over-accumulate for one
+        # run; the data loss the other way was the real cost).
+        label = _key_label(key_path)
+        if label is not None:
+            for k, targets in tuple(watchers.items()):
+                if k is key_path or _key_label(k) != label:
+                    continue
+                try:
+                    targets = tuple(targets or ())
+                except RuntimeError:
+                    return True
+                for ds in targets:
+                    win = getattr(ds, "_lv_window_ds", None)
+                    if win is not None and not getattr(win, "closed", False):
+                        return True
+    except (AttributeError, TypeError):
+        pass
+    return False
+
+
+def _key_label(key_path):
+    """The token name of a `line:N#name` key path (its last segment), else
+    None — the line-free identity a site keeps across re-keys."""
+    tail = key_path[-1] if isinstance(key_path, tuple) and key_path else key_path
+    if not isinstance(tail, str) or not tail.startswith("line:"):
+        return None
+    _, sep, name = tail.partition("#")
+    return name if sep else None
+
+
+_last_wake = 0.0
+
+
+def _notify_watchers(store_obj, key_path, first):
+    """Invalidate every draw_state watching this key (the terminal-reader
+    pattern: invalidate from the publishing thread, render loop repaints) and
+    wake the render loop at most ~30/s so a hot training loop can't spin it.
+    First publishes additionally fire the first-only watcher set."""
+    attrs = ("__live_watchers__", "__live_first_watchers__") if first else (
+        "__live_watchers__",)
+    notified = False
+    for attr in attrs:
+        watchers = getattr(store_obj, attr, None)
+        if not watchers:
+            continue
+        try:
+            targets = tuple(watchers.get(key_path) or ())
+        except RuntimeError:  # concurrent registration resized the set
+            continue
+        for ds in targets:
+            try:
+                ds.invalidate()
+                notified = True
+            except Exception:
+                pass
+            # The open value WINDOW is a nested root - the marker's
+            # invalidate stops at its own tile + ancestors and never
+            # reaches the window tile, - a rerun's publish leaves the
+            # window blitting the stale value. Invalidate FORCE-down its
+            # subtree via the marker's window handle (the draw_function
+            # completion pattern - safe from the publishing thread).
+            win = getattr(ds, "_lv_window_ds", None)
+            if win is not None and not getattr(win, "closed", False):
+                try:
+                    from meltygui.core.melty import Melty
+                    Melty.cache.invalidate_up(win._tile_id, force=True,
+                                              max_depth=8)
+                    notified = True
+                except Exception:
+                    pass
+    if first:
+        # A brand-new key: wake the store-level watchers (usually editors)
+        # so the overlay re-runs and materializes this key's marker.
+        try:
+            store_targets = tuple(
+                getattr(store_obj, "__live_store_watchers__", None) or ())
+        except RuntimeError:
+            store_targets = ()
+        for ds in store_targets:
+            try:
+                ds.invalidate()
+                notified = True
+            except Exception:
+                pass
+    if not notified:
+        return
+    _wake_render(throttle=True)
+
+
+_wake_timer = None
+
+
+def _wake_render(throttle):
+    """Wake the render loop. throttle=True rate-limits to ~30/s — but with a
+    TRAILING edge: a wake that falls inside the window arms a one-shot
+    timer, so the LAST publish of a burst always gets painted. Without it a
+    run's final publish landed inside the window of the one before, the
+    invalidation sat pending with the loop asleep, and the window stayed on
+    whatever intermediate layer the previous frame had caught."""
+    global _last_wake, _wake_timer
+    now = time.time()
+    if throttle and now - _last_wake <= 0.033:
+        if _wake_timer is None:
+            t = threading.Timer(0.04, _wake_render, kwargs={"throttle": False})
+            t.daemon = True
+            _wake_timer = t
+            t.start()
+        return
+    _last_wake = now
+    _wake_timer = None
+    try:
+        from meltygui.core.windowing.glfw_utils import request_render
+        request_render()
+    except Exception:
+        pass  # headless (tests) - nothing to wake
+
+
+def settle_store(store_obj, keys):
+    """Run-end pass: re-invalidate every watcher of `keys` and wake the loop
+    UNTHROTTLED, so the state rendered after a run is the run's FINAL state —
+    intermediate frames during a long run are fine, landing on one is not."""
+    for key in tuple(keys or ()):
+        try:
+            _notify_watchers(store_obj, key, first=False)
+        except Exception:
+            pass
+    _wake_render(throttle=False)
+
+
+# ── capture internals ─────────────────────────────────────────────────────────
+
+def _site_for(code, lineno):
+    per_code = _sites.get(id(code))
+    if per_code is not None and lineno in per_code:
+        return per_code[lineno]
+    with _lock:
+        per_code = _sites.get(id(code))
+        if per_code is None:
+            per_code = {}
+            _sites[id(code)] = per_code
+            weakref.finalize(code, _sites.pop, id(code), None)
+    # Resolve under the lock; a racing duplicate resolution writes the same
+    # result twice.
+    if lineno not in per_code:
+        try:
+            site = _resolve_site(code, lineno)
+        except Exception as e:
+            print(f"live_view: site resolution failed for "
+                  f"{code.co_filename}:{lineno}: {e!r}", file=sys.stderr)
+            site = None
+        per_code[lineno] = site
+    return per_code[lineno]
+
+
+def _publish(site, value, name, bare, dims=None, idx=None):
+    try:
+        # setdefault on the object's __dict is atomic under the GIL, so two
+        # threads first-publishing to a function can't drop a store.
+        store = vars(site.store_obj).setdefault("__live_values__", {})
+    except (AttributeError, TypeError):
+        return
+    first = site.key_path not in store
+    # Register on EVERY publish, not just a key's first - the store rides
+    # the function object and outlives the session, so after a restart
+    # every key is already "known" and a first-only registration left the
+    # owner registry EMPTY - release_all_live_stores (cleanup, the OOM
+    # responder) then dropped nothing. WeakSet.add is O(1).
+    _register_store_owner(site.store_obj)
+    label = name or (site.var_name if bare else site.arg_label)
+    if label:
+        vars(site.store_obj).setdefault("__live_labels__", {})[
+            site.key_path] = label
+    # Re-keyed site (an edit above it moved `line:N#name` to `line:M#name`):
+    # rename the OLD key's entry in place before this first publish, so the
+    # two generations never coexist - the marker/window names (ordinal
+    # among same-label keys), the watcher sets, the accumulator and the
+    # value all carry over, the end-of-run pass sees nothing removed, and
+    # nothing needs invalidating beyond this key's own publish.
+    _adopt_rekeyed(site.store_obj, site.key_path, store)
+    # A loop site accumulates: the store holds the growing stack/list, the
+    # raw per-iteration value only feeds the type recorder below. Must run
+    # BEFORE the touched.add - "key not yet touched this run" is how the
+    # accumulator detects a fresh run and resets.
+    display = value
+    if dims and not has_visible_widget(site.store_obj, site.key_path):
+        # Loop site nobody is LOOKING at: don't stack (a 32-layer stack of
+        # hidden states is gigabytes PER key, repeated for every hidden
+        # widget). Drop any existing stack and park a hint in its place -
+        # opening the widget shows it, and the next run, with the window
+        # now watching, accumulates for real.
+        try:
+            vars(site.store_obj).get("__live_accum__", {}).pop(
+                site.key_path, None)
+        except Exception:
+            pass
+        display = rerun_hint(site.store_obj, site.key_path)
+    elif dims:
+        try:
+            display = _accumulate(site.store_obj, site.key_path, value,
+                                  tuple(dims), idx)
+        except Exception as e:
+            # Never break the publish; drop the entry so the next one restarts.
+            try:
+                vars(site.store_obj).get("__live_accum__", {}).pop(
+                    site.key_path, None)
+            except Exception:
+                pass
+            print(f"live_view: accumulate failed for {site.key_path}: {e!r}",
+                  file=sys.stderr)
+            display = value
+    touched = vars(site.store_obj).get("__live_touched__")
+    if touched is not None and site.key_path not in touched and not first:
+        # FIRST publish of this key in a fresh run: the store is about to
+        # drop the previous generation of value - make sure it actually
+        # dies. The window's marker / draw_states pin the value they just
+        # rendered (and the window's GL volume / cuda_view cache pins it
+        # too) until they re-render, which doesn't happen until the run is
+        # done publishing - so without this every visible view kept the OLD
+        # generation alive for the whole run and peak VRAM was 2× (views
+        # hidden → 1×, the tell). Release now; the window refills from the
+        # store on its next frame (the publish below notifies it).
+        _release_key_watchers(site.store_obj, site.key_path)
+    # The value is stored RAW - a single object assignment, atomic under the
+    # GIL, so the rendering thread always reads either the old or new value.
+    _stamp_publish_gen(display)
+    store[site.key_path] = display
+    if first:
+        bump_keys_gen(site.store_obj)   # key set grew - view names re-rank
+    # Publish ORDER, one int per key: the inline USAGE labels resolve a
+    # usage to the binding above it that actually published LAST (the
+    # branch-not-taken rule - see live_usage.governing_key). Monotonic
+    # across the process via the shared generation counter.
+    try:
+        _sv = vars(site.store_obj)
+        _sv.setdefault("__live_pub_seq__", {})[
+            site.key_path] = next(_PUBLISH_GEN)
+        # Store-level publish generation: the usage marker memoizes each
+        # occurrence's governing key against it (live_view_views).
+        _sv["__live_pub_gen__"] = _sv.get("__live_pub_gen__", 0) + 1
+    except (AttributeError, TypeError):
+        pass
+    # Run-scope liveness: while a run_capture is active for this store,
+    # every published key is recorded so the run's exit can prune the rest
+    # (set.add - atomic under the GIL).
+    if touched is not None:
+        touched.add(site.key_path)
+    _record_scope_type(site, value, name, bare)
+    _notify_watchers(site.store_obj, site.key_path, first=first)
+
+
+# Sliding-window cap for a loop-site publishing outside any run_capture
+# scope (a free-running training loop has no run boundary to stop at).
+_ACCUM_CAP = 512
+
+
+def _accumulate(store_obj, key_path, value, dims, idx):
+    """Fold one LOOP-SITE publish into its per-key accumulator and return the
+    DISPLAY value the store should hold: tensors/ndarrays append along a new
+    leading dim (a doubling growth buffer — amortized O(1) per publish, no
+    per-iteration restack), everything else appends to a list.
+
+    `dims` is the static tuple of enclosing-loop names, outermost first
+    (`for l_idx, layer in enumerate(…)` → 'l_idx'; while → 'iter'); `idx` is
+    those loop variables' CURRENT values read from the publishing frame.
+    An all-int idx keys the entry by ITERATION INDEX, so a repeated pass
+    (an outer epoch loop, a re-called function) OVERWRITES in place instead
+    of growing — natural rollover — and a complete rectangular nested grid
+    reshapes into one named dim PER loop. Non-int idx (`for layer in
+    layers`, while bodies) appends flat in publish order; nested loops that
+    can't grid flatten under a composite ' × '-joined name.
+
+    The auto dim names land in __live_dim_names__[key_path] (read by the
+    editor marker, which prepends them to the site's user dim_names before
+    the value-window call). A run_capture scope resets a key's accumulator
+    on its first publish of the run — the store keeps showing the finished
+    stack between runs. Tensors are detached first: a graph-carrying stack
+    would pin autograd memory across the whole loop."""
+    try:
+        accums = vars(store_obj).setdefault("__live_accum__", {})
+    except (AttributeError, TypeError):
+        return value
+    kind = type(value).__name__
+    stackable = (kind == "Tensor"
+                 or (kind == "ndarray" and value.dtype.kind in "fiub"))
+    if kind == "Tensor":
+        try:
+            value = value.detach()
+        except Exception:
+            pass
+    touched = vars(store_obj).get("__live_touched__")
+    ent = accums.get(key_path)
+    if (ent is None or ent["dims"] != dims
+            or (touched is not None and key_path not in touched)):
+        # A fresh run's stack almost always ends the same size as the last
+        # one (same loop) - size the buffer to that at the start instead
+        # of doubling up to it: each doubling step held the old + new
+        # buffer (the 16→32 step on a 32-layer (32, 1413, 1413) stack is
+        # a 2 GB + 4 GB transient per key) - on a card that's full, the
+        # transient IS the OOM.
+        hint = 0
+        if ent is not None and ent["dims"] == dims:
+            hint = int(ent["n"] or ent.get("hint", 0))
+        ent = accums[key_path] = {
+            "dims": dims,   # static loop names, outermost first
+            "slots": {},    # idx tuple | ('#', n) counter -> row/seq position
+            "buf": None,    # stack growth buffer (cap, *shape) | None
+            "n": 0,         # buffer rows in use
+            "seq": None,    # list fallback (non-stackable / ragged shapes)
+            "hint": hint,   # last run's final row count - the initial cap
+        }
+    by_index = (idx is not None and len(idx) == len(dims)
+                and all(type(i) is int for i in idx))
+    slot_key = tuple(idx) if by_index else ("#", len(ent["slots"]))
+
+    buf = ent["buf"]
+    if buf is not None and (not stackable
+                            or (kind == "Tensor") != (type(buf).__name__
+                                                      == "Tensor")
+                            or tuple(buf.shape[1:]) != tuple(value.shape)):
+        # Genuinely ragged (not the value's shape): give up the packed
+        # buffer, keep the rows (views into it) and continue as a plain
+        # list. Dtype/device drift is NOT a deopt - copy_ casts and crosses
+        # devices below, so a sharded/offloaded model's per-layer values
+        # still stack into the first layer's buffer.
+        print(f"live_view: {key_path} accumulates as a list — "
+              f"{getattr(value, 'shape', type(value).__name__)} doesn't "
+              f"stack on buffer {tuple(buf.shape[1:])}", file=sys.stderr)
+        ent["seq"] = [buf[i] for i in range(ent["n"])]
+        ent["buf"] = buf = None
+
+    if not stackable or ent["seq"] is not None:
+        seq = ent["seq"]
+        if seq is None:
+            seq = ent["seq"] = []
+        pos = ent["slots"].get(slot_key)
+        if pos is not None and pos < len(seq):
+            seq[pos] = value
+        else:
+            ent["slots"][slot_key] = len(seq)
+            seq.append(value)
+            if len(seq) > _ACCUM_CAP:
+                del seq[0]
+                ent["slots"] = {("#", i): i for i in range(len(seq))}
+        _stamp_auto_dims(store_obj, key_path, dims, nested=False)
+        return seq
+
+    if buf is None:
+        buf = ent["buf"] = _accum_alloc(
+            value, max(4, min(_ACCUM_CAP, int(ent.get("hint", 0)))))
+    pos = ent["slots"].get(slot_key)
+    if pos is None:
+        if ent["n"] >= _ACCUM_CAP:
+            # Sliding window: pop off the oldest row. Index identity is
+            # gone after a window, so slots degrade to flat counters.
+            src = buf[1:ent["n"]]
+            buf[:ent["n"] - 1] = (src.clone() if kind == "Tensor"
+                                  else src.copy())
+            pos = ent["n"] - 1
+            ent["slots"] = {("#", i): i for i in range(pos + 1)}
+        else:
+            if ent["n"] >= buf.shape[0]:
+                # Grow from the BUFFER's dtype/device (not the value's - a
+                # drifting value must not silently re-home the whole stack).
+                cap = min(_ACCUM_CAP, max(4, buf.shape[0] * 2))
+                if kind == "Tensor":
+                    new = buf.new_empty((cap,) + tuple(buf.shape[1:]))
+                else:
+                    import numpy as np
+                    new = np.empty((cap,) + tuple(buf.shape[1:]),
+                                   dtype=buf.dtype)
+                new[:ent["n"]] = buf[:ent["n"]]
+                buf = ent["buf"] = new
+            pos = ent["n"]
+            ent["n"] += 1
+            ent["slots"][slot_key] = pos
+    if kind == "Tensor":
+        # copy_ casts dtype and crosses devices - mixed-precision layers and
+        # device_map-sharded models stack instead of deopting to a list.
+        buf[pos].copy_(value)
+    else:
+        buf[pos] = value
+
+    flat = buf[:ent["n"]]
+    nested = False
+    if len(dims) > 1 and ent["n"]:
+        ks = list(ent["slots"])
+        if all(k[0] != "#" for k in ks) and ks == sorted(ks):
+            extents = tuple(len({k[d] for k in ks})
+                            for d in range(len(dims)))
+            total = 1
+            for e in extents:
+                total *= e
+            if total == ent["n"]:
+                flat = flat.reshape(extents + tuple(buf.shape[1:]))
+                nested = True
+    _stamp_auto_dims(store_obj, key_path, dims, nested)
+    return flat
+
+
+def _accum_alloc(value, cap):
+    """An uninitialized (cap, *value.shape) buffer matching value's dtype
+    (and device, for torch tensors)."""
+    if type(value).__name__ == "Tensor":
+        return value.new_empty((cap,) + tuple(value.shape))
+    import numpy as np
+    return np.empty((cap,) + tuple(value.shape), dtype=value.dtype)
+
+
+def _stamp_auto_dims(store_obj, key_path, dims, nested):
+    """Record the accumulated dims' auto names for the editor marker: one
+    name per loop when the stack is nested (or single-loop), a composite
+    ' × ' name for a flattened multi-loop stack."""
+    names = tuple(dims) if (nested or len(dims) == 1) else (" × ".join(dims),)
+    try:
+        stamped = vars(store_obj).setdefault("__live_dim_names__", {})
+        stamped[key_path] = names
+    except (AttributeError, TypeError):
+        pass
+
+
+def auto_dim_names_for(obj, key_path):
+    """The auto loop-dim names a key's accumulated value carries (leading
+    dims, outermost first), or None. Editor-side reader — the marker
+    prepends these to the site's user dim_names before the value-window
+    call."""
+    try:
+        obj = inspect.unwrap(obj)
+    except Exception:
+        pass
+    names = getattr(obj, "__live_dim_names__", None)
+    return names.get(key_path) if names else None
+
+
+def _record_scope_type(site, value, name, bare):
+    """Feed the published value's runtime type into FuncsMetadata, keyed by the
+    owning function — so an editor on that function's source autocompletes
+    `x.` against the LIVE type of x, for every local a live_view / snapshot
+    run has seen. This is the mid-body complement to the context menu's stack
+    capture (which only sees callers' frames and the target's entry kwargs).
+
+    The recorded NAME must be a real local: the bare form's resolved
+    assignment target, or an explicit call's arg source when it is a plain
+    identifier (`live_view(attn_weights, ...)`); expression args (`x[0].w`)
+    and display-only `name=` labels are skipped. One exception: a snapshot
+    stamp (instrumented_twin's injected `__lv_view__(x, name='x')`) has NO
+    call in the SOURCE at its line, so the site carries no arg_label — there
+    the injected `name` IS the assignment target by construction, and only
+    then is it trusted as the local's name. Module/class-body stores are
+    skipped too — module-level names already complete via the live namespace
+    walk. Cheap on hot publish paths: record_value no-ops on an unchanged
+    type. Best-effort; a hiccup must never break a publish."""
+    store_obj = site.store_obj
+    if not isinstance(store_obj, types.FunctionType):
+        return
+    local_name = site.var_name if bare else site.arg_label
+    if not (isinstance(local_name, str) and local_name.isidentifier()):
+        if not (site.arg_label is None and not bare and isinstance(name, str)):
+            return
+        local_name = name
+        if not local_name.isidentifier():
+            return
+    try:
+        from meltygui.core.rendering.func_metadata import FuncsMetadata
+        FuncsMetadata.record_value(store_obj, local_name, value)
+    except Exception:
+        pass
+
+
+# The single owner of the run_capture currently open on THIS thread (a small
+# stack: nested captures are possible in principle). twin_snap publishes to
+# it instead of re-resolving the store by (file, line): the resolver walk can
+# find a DIFFERENT function object than the one being run (the module's real
+# function vs the def-run path's exec'd twin parked beside it - same
+# co_firstlineno, first-in-dict wins), and the run_capture prunes one store
+# while the run fills another: stale keys (every renamed/removed site,
+# each with its accumulated stack) were never swept, and the accumulator
+# never saw a fresh run - the "accumulators still growing" symptom.
+_run_owner = threading.local()
+
+
+def current_run_owner():
+    stack = getattr(_run_owner, "stack", None)
+    return stack[-1] if stack else None
+
+
+def _register_store_owner(store_obj):
+    try:
+        _store_owners.add(store_obj)
+    except TypeError:
+        pass          # not weak-referenceable - won't be swept, fine
+
+
+def _discover_store_owners():
+    """Every function object carrying a live store, found by a gc walk —
+    the fallback for a registry that missed owners. A module scan is NOT
+    enough: the store rides the function OBJECT, and a recompile/hotswap
+    replaces the module's attribute while the superseded function lives on
+    (the `_sites` cache holds it via Site.store_obj) with its whole store —
+    14 GB of stacks in one session, reachable from nothing nameable.
+    Unfreezes first: gc_manager freezes the boot generation and
+    gc.get_objects() skips frozen objects. OOM-time only (opt-in via
+    release_all_live_stores(discover=True)): the walk is O(the process
+    heap) — ~0.5 s for one session, but the model_server process keeps
+    prior sessions' graphs, so it grows with every launch. Never run it
+    on the session-teardown path."""
+    import gc
+    try:
+        gc.unfreeze()
+    except Exception:
+        pass
+    found = []
+    for o in gc.get_objects():
+        if not isinstance(o, types.FunctionType):
+            continue
+        try:
+            d = vars(o)
+        except TypeError:
+            continue
+        if "__live_values__" in d or "__live_accum__" in d:
+            found.append(o)
+    return found
+
+
+def release_all_live_stores(discover=False):
+    """Drop EVERY live-view store: values, loop accumulators (the per-run
+    stacks — gigabytes), labels, watchers; close/release every marker and
+    value window that watched them (GL textures included, via
+    release_live_value). The CUDA-OOM response: after an out-of-memory the
+    live set IS the VRAM, and a partial run's stacks + every window's pinned
+    generation must go before anything can run again. Markers re-publish
+    and windows re-fill on the next run; nothing is lost that a run doesn't
+    recreate. Returns the number of keys dropped. Safe from any thread.
+
+    Owners come from the `_store_owners` registry, which is complete for
+    this module instance: `_publish` registers on EVERY publish, and
+    `run_capture` / `adopt_live_store` register too. `discover=True` adds
+    the `_discover_store_owners` gc walk as a belt-and-braces fallback —
+    O(the whole process heap), and the model_server process carries prior
+    sessions' graphs (see gc_manager._boot_collect_and_freeze), so at
+    session teardown that walk grew with every launch: the multi-second
+    hang after "Cleaning CUDA context". Melty.cleanup therefore uses the
+    registry alone; the OOM responder, a rare recovery where a missed
+    14 GB store costs more than the walk, still discovers."""
+    dropped = 0
+    owners = list(_store_owners)
+    if discover:
+        known = {id(o) for o in owners}
+        for o in _discover_store_owners():
+            if id(o) not in known:
+                owners.append(o)
+                _register_store_owner(o)
+    for owner in owners:
+        try:
+            store = vars(owner).get("__live_values__")
+        except TypeError:
+            continue
+        keys = list(store) if store else []
+        if keys:
+            _prune_keys(owner, keys)
+            dropped += len(keys)
+        # Anything _prune_keys leaves behind (a key that never published a
+        # value but has an accumulator entry, a fresh-run scope, ...).
+        for attr in ("__live_accum__", "__live_dim_names__", "__live_touched__"):
+            try:
+                d = vars(owner).get(attr)
+                if hasattr(d, "clear"):
+                    d.clear()
+            except TypeError:
+                pass
+    return dropped
+
+
+@contextmanager
+def run_capture(store_obj):
+    """Scope one instrumented run over `store_obj` (pass the UNWRAPPED
+    function — the object capture attaches to). Keys published inside the
+    with-block are recorded, and a SUCCESSFUL exit prunes every other key:
+    an instrumented run republishes every assignment it still contains, so
+    anything not touched is a REMOVED line — without this, stale keys linger
+    forever as ghost markers, orphaned value windows, and line:N entries
+    that jumble future resolution. An exception skips the prune: a partial
+    run proves nothing about which sites still exist."""
+    try:
+        vars(store_obj)["__live_touched__"] = set()
+    except (AttributeError, TypeError):
+        yield
+        return
+    _register_store_owner(store_obj)
+    # The previous generation goes BEFORE the run allocates the next generation -
+    # every big value in the store (and the watchers' pins to it), not just
+    # the keys this run fails to republish: an edit that removes a line
+    # re-keys every `line:N#...` site below it, so the per-key release in
+    # _publish never fires for them: the old stacks would live until the
+    # end-of-run prune (or past it, if the run OOMs - a failed run prunes
+    # nothing). Windows hold their last frame anyway; small values
+    # (scalars, strings) stay so text markers don't blink.
+    _release_store_generation(store_obj)
+    stack = getattr(_run_owner, "stack", None)
+    if stack is None:
+        stack = _run_owner.stack = []
+    stack.append(store_obj)
+    try:
+        yield
+    except BaseException:
+        touched = vars(store_obj).pop("__live_touched__", None)
+        # A failed run (OOM mid-loop) still re-paints what it did publish
+        # - the windows must show the store's truth, not a stale frame.
+        settle_store(store_obj, touched)
+        raise
+    finally:
+        if stack and stack[-1] is store_obj:
+            stack.pop()
+    touched = vars(store_obj).pop("__live_touched__", set())
+    _prune_untouched(store_obj, touched)
+    settle_store(store_obj, touched)
+
+
+_RELEASE_MIN_BYTES = 1 << 20
+
+
+def _big_tensorish(v, min_bytes=_RELEASE_MIN_BYTES):
+    kind = type(v).__name__
+    try:
+        if kind == "Tensor":
+            return v.numel() * v.element_size() >= min_bytes
+        if kind == "ndarray":
+            return v.nbytes >= min_bytes
+    except Exception:
+        return False
+    return False
+
+
+def _release_store_generation(store_obj, min_bytes=_RELEASE_MIN_BYTES):
+    """Drop every big tensor/ndarray value in `store_obj`'s store (the entry
+    stays, value None — the marker still reads as captured and its window
+    holds its last frame), clear the matching accumulator buffers (keeping
+    the row count as the next run's pre-size hint), and release the
+    watchers' pins. Returns the number of values released. Any thread."""
+    try:
+        store = vars(store_obj).get("__live_values__")
+        accums = vars(store_obj).get("__live_accum__") or {}
+    except TypeError:
+        return 0
+    if not store:
+        return 0
+    n = 0
+    for key in list(store):
+        v = store.get(key)
+        if not _big_tensorish(v, min_bytes):
+            continue
+        store[key] = None
+        ent = accums.get(key)
+        if ent is not None:
+            ent["hint"] = int(ent.get("n") or ent.get("hint", 0))
+            ent["buf"] = None
+            ent["seq"] = None
+            ent["slots"] = {}
+            ent["n"] = 0
+        _release_key_watchers(store_obj, key)
+        n += 1
+    return n
+
+
+def _release_key_watchers(store_obj, key_path):
+    """Drop the captured-value refs (+ GL resources) held by every marker and
+    value window watching `key_path` — WITHOUT closing them or touching the
+    store. The per-run peak-VRAM guard (see _publish); same release as a
+    prune, minus the prune. Any thread."""
+    try:
+        from meltygui.editor.live_view_views import release_live_value
+    except Exception:
+        return
+    for attr in ("__live_watchers__", "__live_first_watchers__"):
+        watchers = getattr(store_obj, attr, None)
+        if not watchers:
+            continue
+        try:
+            targets = tuple(watchers.get(key_path) or ())
+        except RuntimeError:
+            targets = ()
+        for ds in targets:
+            try:
+                release_live_value(ds, gl=False)
+                win = getattr(ds, "_lv_window_ds", None)
+                if win is not None:
+                    # keep the FBO's last image: the window shows its last
+                    # frame until the fresh value lands (no error flash)
+                    release_live_value(win, keep_image=True)
+            except Exception:
+                pass
+
+
+def _retained_markers(store_obj, store, removed):
+    """ids of watcher draw_states (markers) of `removed` keys that must keep
+    their window: the marker still serves a SURVIVING key. Two tests, either
+    suffices:
+      - identity: the same ds is registered under a surviving key (the
+        marker rendered since the re-key and re-watched);
+      - stable name: the removed key's line-free name (label + ordinal
+        among same-label keys, the convention marker/window names already
+        use — live_view_views._stable_key_names) is also the name of a
+        surviving key. Old-generation names rank over removed ∪ survivors
+        that already have watchers (keys published before this run);
+        new-generation names over the survivors — so an in-def shift of
+        every `hidden` site keeps every `hidden` window.
+    Markers are name-keyed (`lvs::fn::hidden#1`), so a site that moved
+    lines comes back as the SAME draw_state — nothing to hand over."""
+    keep = set()
+    removed_set = set(removed)
+    survivors = [k for k in store if k not in removed_set]
+    if not survivors:
+        return keep
+    watcher_maps = []
+    for attr in ("__live_watchers__", "__live_first_watchers__"):
+        w = getattr(store_obj, attr, None)
+        if w:
+            watcher_maps.append(w)
+
+    def _targets(k):
+        out = []
+        for w in watcher_maps:
+            try:
+                out.extend(tuple(w.get(k) or ()))
+            except RuntimeError:
+                pass
+        return out
+
+    surviving_ds = set()
+    old_gen = list(removed_set)
+    for k in survivors:
+        t = _targets(k)
+        if t:
+            surviving_ds.update(id(d) for d in t)
+            old_gen.append(k)
+    try:
+        from meltygui.editor.live_view_views import _stable_key_names
+        old_names = _stable_key_names(old_gen)
+        new_names = set(_stable_key_names(survivors).values())
+    except Exception:
+        old_names, new_names = {}, set()
+    for k in removed:
+        for d in _targets(k):
+            if id(d) in surviving_ds or old_names.get(k) in new_names:
+                keep.add(id(d))
+    return keep
+
+
+def _prune_untouched(store_obj, touched):
+    """Drop every store key not in `touched` — run_capture's whole-store sweep.
+    The per-key removal mechanics live in _prune_keys (shared with the frame-
+    snapshot publisher, which prunes only ITS OWN stale keys)."""
+    store = getattr(store_obj, "__live_values__", None)
+    if not store:
+        return
+    _prune_keys(store_obj, [k for k in tuple(store) if k not in touched])
+
+
+def _prune_keys(store_obj, removed):
+    """Remove the given store keys: value, label, per-key watcher sets, and
+    any open value window (win.closed = True — the next root_draw_states
+    dispatch discards it; if the key ever republishes, the marker re-registers
+    its window with closed= driven fresh). Store-level watchers (the snapshot
+    editors) are invalidated so the overlay re-runs without the removed
+    markers. Safe from any thread — dict pops/copies are GIL-atomic and
+    ds.invalidate() is the established cross-thread completion pattern."""
+    store = getattr(store_obj, "__live_values__", None)
+    if not store or not removed:
+        return
+    labels = getattr(store_obj, "__live_labels__", None)
+    # Line shifts: keys are line-anchored (`line:N#name`), so an edit that
+    # inserts/removes a line above a site re-keys it - the old key lands
+    # here as "removed" while the SAME assignment republished under
+    # `line:M#name`, served by the SAME name-keyed marker. Its window must
+    # survive (see _retained_markers); only markers whose site is really
+    # gone are closed.
+    keep = _retained_markers(store_obj, store, removed)
+    # One-time cleanup of the (temporary) parking lot: windows parked
+    # under __live_window_handoff__ were never adopted and sat orphaned.
+    try:
+        for _w in (vars(store_obj).pop("__live_window_handoff__", None)
+                   or {}).values():
+            _w.closed = True
+    except Exception:
+        pass
+    for key in removed:
+        store.pop(key, None)
+        if labels:
+            labels.pop(key, None)
+        for _attr in ("__live_accum__", "__live_dim_names__"):
+            _d = getattr(store_obj, _attr, None)
+            if _d:
+                _d.pop(key, None)
+        for attr in ("__live_watchers__", "__live_first_watchers__"):
+            watchers = getattr(store_obj, attr, None)
+            if not watchers:
+                continue
+            try:
+                targets = tuple(watchers.pop(key, None) or ())
+            except RuntimeError:
+                targets = ()
+            for ds in targets:
+                if id(ds) in keep:
+                    # The same marker (name-stable: line stripped, ordinal
+                    # among same-label keys) still serves a surviving key -
+                    # the site moved lines, it didn't go away. Its window
+                    # stays open and pinned; the marker re-watches the new
+                    # key on its next render (an open window keeps it out
+                    # of _marker_idle_skip).
+                    continue
+                win = getattr(ds, "_lv_window_ds", None)
+                if win is not None:
+                    try:
+                        win.closed = True
+                    except Exception:
+                        pass
+                try:
+                    ds._lv_open = False
+                    ds.invalidate()
+                except Exception:
+                    pass
+                # The marker and its window stop rendering for good (the key
+                # is gone) but their draw_states persist: drop the captured
+                # value they hold (and the window's GPU texture), or every
+                # pruned key leaves a generation of tensors for the session.
+                try:
+                    from meltygui.editor.live_view_views import release_live_value
+                    release_live_value(ds, gl=False)
+                    if win is not None:
+                        release_live_value(win)
+                except Exception:
+                    pass
+    bump_keys_gen(store_obj)        # key set shrank - view names re-rank
+    try:
+        store_targets = tuple(
+            getattr(store_obj, "__live_store_watchers__", None) or ())
+    except RuntimeError:
+        store_targets = ()
+    for ds in store_targets:
+        try:
+            ds.invalidate()
+        except Exception:
+            pass
+    try:
+        from meltygui.core.windowing.glfw_utils import request_render
+        request_render()
+    except Exception:
+        pass  # headless (test)
+
+
+_STORE_ATTRS = ("__live_values__", "__live_accum__", "__live_labels__",
+                "__live_dim_names__", "__live_watchers__",
+                "__live_first_watchers__", "__live_store_watchers__",
+                "__frame_snapshot_keys__",
+                "__live_return_line__", "__live_error_line__")
+# (__live_touched__ stays put: it is an in-flight run_capture's marker on the
+# OLD function - moving it would just make that run prune an empty store.)
+
+
+def adopt_live_store(old, new):
+    """Move the live-view store from one function object to its SUCCESSOR —
+    the def-run path (text_editor._fnrun_resolve) exec-compiles a FRESH
+    function per body edit, and the old one — unreachable from any module
+    var once re-parked — still owned its whole `__live_values__` /
+    `__live_accum__` (the per-layer stacks: gigabytes per run). One owner
+    per def: `new` takes over the dicts BY IDENTITY (watchers, markers and
+    open value windows keep working unchanged — publishes to `new` land in
+    the same dicts), and `old` drops them, so a superseded function pins
+    nothing. If `new` already has a store (the real module function that ran
+    before its exec twin did) its own wins and the old one is just dropped —
+    the memory, not the continuity, is what matters."""
+    if old is None or new is None or old is new:
+        return
+    try:
+        od, nd = vars(old), vars(new)
+    except TypeError:
+        return
+    for attr in _STORE_ATTRS:
+        if attr not in od:
+            continue
+        moved = od.pop(attr)
+        if attr not in nd:
+            nd[attr] = moved
+    _register_store_owner(new)
+
+
+def clear_file_stores(filename):
+    """Drop EVERY captured live_view value riding this file's stores: the
+    module object plus each function/method whose code lives in the file
+    (unwrapped — capture attaches to the inner function). Goes through
+    _prune_keys, so open value windows close, marker dots flip back to gray
+    and store-level watchers repaint; per-run markers (return/error line
+    washes) are dropped too. The editor's live-badge × calls this. Returns
+    the number of values dropped."""
+    from meltygui.code.chain_converters import _module_for_file
+    try:
+        path = Path(filename).resolve()
+    except Exception:
+        return 0
+    mod = _module_for_file(path)
+    if mod is None:
+        return 0
+    fname = str(path)
+    objs, seen = [mod], {id(mod)}
+
+    def _collect(ns):
+        for v in list(ns.values()):
+            try:
+                v = inspect.unwrap(v)
+            except Exception:
+                pass
+            if id(v) in seen:
+                continue
+            code = getattr(v, "__code__", None)
+            if code is not None and getattr(code, "co_filename", None) == fname:
+                seen.add(id(v))
+                objs.append(v)
+            elif (isinstance(v, type)
+                  and getattr(v, "__module__", None) == getattr(mod, "__name__", None)):
+                seen.add(id(v))
+                _collect(dict(vars(v)))
+
+    _collect(dict(vars(mod)))
+    dropped = 0
+    for obj in objs:
+        store = getattr(obj, "__live_values__", None)
+        if store:
+            keys = tuple(store)
+            dropped += len(keys)
+            _prune_keys(obj, keys)
+        d = getattr(obj, "__dict__", None)
+        if d is not None:
+            for attr in ("__live_return_line__", "__live_error_line__",
+                         "__live_touched__", "__live_accum__",
+                         "__live_dim_names__"):
+                d.pop(attr, None)
+    return dropped
+
+
+# ── frame snapshots (context-menu capture -> live-value stores) ──────────────
+# The context menu's stack entry holds every called frame's fscope for one
+# snapshot. Publishing them through the SAME site/key pipeline the instrumented
+# twin uses makes them first-class live values: markers, live value windows,
+# watchers, voxel, and FuncsMetadata typing all come along for free, in
+# ANY editor that shows the function - no new rendering machinery.
+
+def publish_frame_snapshot(fn, scope, upto_lineno=None):
+    """Publish a ``{name: value}`` scope snapshot into ``fn``'s live-value
+    store, anchored at EVERY occurrence of each name in the def's own scope:
+    parameters at their signature lines, and every Name reference — Load and
+    Store alike (assignments in all forms, loop/with targets, walrus, and
+    plain reads) — so any mention of a local in the source is a live view,
+    not just its binding. One key per (name, line); all of a name's markers
+    show the same captured value. ``upto_lineno`` is accepted for API
+    stability but no longer gates anchors: the snapshot IS the frame's state
+    at capture, and every reference line is an equally valid place to
+    inspect it.
+
+    Deliberately NO site resolution: keys are synthesized ``line:N#name``
+    tails, which the overlay anchors by line and boxes by label. The
+    structural key `_resolve_site` derives costs a libcst parse of the whole
+    enclosing span (~240ms for draw_collection, the whole CLASS for a
+    method) and produces a prefix the overlay ignores for line-keyed
+    entries. Total cost here: one cached whole-file ast + one walk of the
+    def + N dict writes.
+
+    Keys this publisher created in a PREVIOUS snapshot that this one didn't
+    re-touch are pruned (``__frame_snapshot_keys__`` on ``fn``) so edits
+    between menu-opens can't leave ghost markers; keys owned by other
+    writers (manual live_view calls, twin runs) are never touched.
+
+    Accepts a render_func WRAPPER too — unwrapped here, since anchors and
+    the store must live on the real body function (the wrapper's __code__
+    points at core_render)."""
+    fn, items, _def_line = _frame_snapshot_items(fn, scope)
+    if fn is None:
+        return
+    new_keys = set()
+    for disk, n, val in items:
+        site = _Site((f"line:{disk}#{n}",), None, None, fn, disk)
+        _publish(site, val, n, bare=False)
+        new_keys.add(site.key_path)
+    try:
+        prev = vars(fn).get("__frame_snapshot_keys__") or set()
+        _prune_keys(fn, [k for k in prev - new_keys])
+        vars(fn)["__frame_snapshot_keys__"] = new_keys
+    except (AttributeError, TypeError):
+        pass
+
+
+def _frame_snapshot_items(fn, scope, tree=None):
+    """(unwrapped_fn, [(disk_lineno, name, value), ...], def_line) anchoring
+    a ``{name: value}`` scope onto every occurrence of each captured name in
+    ``fn``'s def (see _occurrence_lines) — the pure computation shared by
+    publish_frame_snapshot (global store) and frame_value_store (local
+    store). `def_line` is the DISK line of the `def` STATEMENT itself (the
+    ast node's lineno — NOT co_firstlineno, which points at the first
+    decorator for a decorated function). (None, [], None) when the
+    function/scope can't be resolved.
+
+    A caller that already parsed the file passes `tree` — the stack view
+    hands its project_code ast: no second whole-file parse (the tab-open
+    cost), and the anchor lines come out in THAT text's own coordinates
+    (no pending delta — the caller renders the very same text)."""
+    try:
+        fn = inspect.unwrap(fn)
+    except Exception:
+        pass
+    code = getattr(fn, "__code__", None)
+    if code is None or not isinstance(fn, types.FunctionType) or not scope:
+        return None, [], None
+    if tree is not None:
+        delta = 0
+    else:
+        path = Path(code.co_filename).resolve()
+        try:
+            tree, _text, _sig = _ast_for(path, path.stat().st_mtime)
+        except (OSError, SyntaxError, ValueError):
+            return None, [], None
+        delta = _stamp_delta(path, code.co_firstlineno)  # pending = disk + Δ
+    fdef = _def_node_for(tree, fn, code.co_firstlineno + delta)
+    if fdef is None:
+        return None, [], None
+    anchors = _occurrence_lines(fdef)
+    items = []
+    for n, lns in anchors.items():
+        if "." in n:
+            # Attribute chain (`draw_state.some_val`, each segment of
+            # `a.b.c` anchors separately): resolve the value through the
+            # captured base object - instance __dict__ / plain class attrs
+            # only, never through properties or descriptors (a DrawState
+            # geometry getter must be run on the main worker).
+            ok, val = _resolve_dotted(scope, n)
+            if not ok:
+                continue
+        elif n in scope:
+            val = scope[n]
+        else:
+            continue
+        for ln in lns:
+            items.append((ln - delta, n, val))
+    return fn, items, fdef.lineno - delta
+
+
+class LocalValueStore:
+    """A live-value store computed locally and PASSED IN (draw_text's
+    ``live_store=``) instead of published onto the live function. Same
+    attach-to-object shape the whole live-view stack reads — values, labels
+    and watchers all ride this object (live_values_for, label_for, watch) —
+    so the overlay/marker/window machinery works unchanged, but nothing
+    global ever sees it: two views of two different captures of the same
+    function coexist, and dropping the store releases everything it pinned.
+    `__def_line__` (disk line of the owning def) is how the snapshot overlay
+    matches the store to ITS def node and no other."""
+
+    def __init__(self, qualname="?", def_line=None):
+        self.__qualname__ = qualname
+        self.__name__ = qualname.rsplit(".", 1)[-1]
+        self.__def_line__ = def_line
+        self.__live_values__ = {}
+        self.__live_labels__ = {}
+
+
+def frame_value_store(fn, scope, tree=None):
+    """A LocalValueStore of ``scope`` anchored on ``fn``'s def — the same
+    anchor computation publish_frame_snapshot uses, with NOTHING written to
+    ``fn`` and nothing registered globally. For callers that own their
+    capture (the stack trace view): build once, hand to draw_text as
+    ``live_store=``, drop when done. Pass `tree` (an already-parsed ast of
+    the text being rendered) to skip the whole-file parse and anchor in
+    that text's coordinates. Returns None when unresolvable."""
+    fn, items, def_line = _frame_snapshot_items(fn, scope, tree=tree)
+    if fn is None or not items:
+        return None
+    # def_line is the ast def statement's line - co_firstlineno points at
+    # the first DECORATOR for a decorated function (every _render_func
+    # view), and the overlay's def-match gate compares against the span
+    # parse tree which starts at the def itself: stamping the decorator line
+    # made the gate reject the store and no marker ever drew (08-31).
+    store = LocalValueStore(qualname=getattr(fn, "__qualname__", fn.__name__),
+                            def_line=def_line)
+    for disk, n, val in items:
+        key_path = (f"line:{disk}#{n}",)
+        store.__live_values__[key_path] = val
+        store.__live_labels__[key_path] = n
+    return store
+
+
+def _def_node_for(tree, fn, target_lineno):
+    """``fn``'s FunctionDef in the (pending-text) ast: name match, def line
+    nearest ``target_lineno`` — the co_firstlineno proximity trick
+    live_instrument uses, tolerant of the decorator-line offset. Scans
+    module and class bodies only (a full ast.walk is O(file nodes) per
+    call, and _enclosing_function can't resolve deeper functions anyway)."""
+    best, best_d = None, None
+    want = getattr(fn, "__name__", None)
+
+    def consider(node):
+        nonlocal best, best_d
+        d = abs(node.lineno - target_lineno)
+        if best_d is None or d < best_d:
+            best, best_d = node, d
+
+    for stmt in tree.body:
+        if (isinstance(stmt, (ast.FunctionDef, ast.AsyncFunctionDef))
+                and stmt.name == want):
+            consider(stmt)
+        elif isinstance(stmt, ast.ClassDef):
+            for sub in stmt.body:
+                if (isinstance(sub, (ast.FunctionDef, ast.AsyncFunctionDef))
+                        and sub.name == want):
+                    consider(sub)
+    return best
+
+
+# Scopes a binding walk must NOT descend into: their Store names bind in a
+# DIFFERENT frame (nested defs/classes, lambdas, comprehensions).
+_FOREIGN_SCOPES = (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef,
+                   ast.Lambda, ast.ListComp, ast.SetComp, ast.DictComp,
+                   ast.GeneratorExp)
+
+
+def _occurrence_lines(fdef):
+    """``{name: set of pending linenos}`` of every occurrence of a name in
+    ``fdef``'s own scope: parameters at their signature lines, then EVERY
+    Name node — Store and Load alike — so references anchor live views, not
+    just bindings. (The publisher filters to names actually captured in the
+    frame's scope, which is also what keeps module globals like `imgui` out:
+    they're Load names here but never frame locals.) Pure ATTRIBUTE chains
+    off a Name (`draw_state.some_val`, and each inner segment of `a.b.c`)
+    anchor too, under their dotted spelling — single-line chains only (the
+    overlay boxes the final segment by regex on its line) and never through
+    calls/subscripts (`foo().x` has no frame-resolvable base). Nested
+    defs/classes/lambdas/comprehensions are not descended — their names
+    live in other frames."""
+    anchors = {}
+    a = fdef.args
+    params = list(a.posonlyargs) + list(a.args) + list(a.kwonlyargs)
+    for extra in (a.vararg, a.kwarg):
+        if extra is not None:
+            params.append(extra)
+    for arg in params:
+        anchors.setdefault(arg.arg, set()).add(arg.lineno)
+
+    def walk(node):
+        for child in ast.iter_child_nodes(node):
+            if isinstance(child, _FOREIGN_SCOPES):
+                continue
+            if isinstance(child, ast.Name):
+                anchors.setdefault(child.id, set()).add(child.lineno)
+            elif (isinstance(child, ast.Attribute)
+                  and getattr(child, "end_lineno", child.lineno) == child.lineno):
+                dotted = _dotted_name(child)
+                if dotted is not None:
+                    anchors.setdefault(dotted, set()).add(child.lineno)
+            walk(child)
+
+    walk(ast.Module(body=fdef.body, type_ignores=[]))
+    return anchors
+
+
+def _dotted_name(node):
+    """`a.b.c` for a pure Name-rooted attribute chain, else None (a call,
+    subscript or literal anywhere in the chain has no frame-local base)."""
+    parts = []
+    while isinstance(node, ast.Attribute):
+        parts.append(node.attr)
+        node = node.value
+    if isinstance(node, ast.Name):
+        parts.append(node.id)
+        return ".".join(reversed(parts))
+    return None
+
+
+def _safe_attr_value(base, attr):
+    """(ok, value) of ``base.attr`` WITHOUT running any code: instance
+    __dict__ first, then a plain class attribute via getattr_static —
+    properties, descriptors, and class-level functions (methods) are
+    refused rather than fired or published as noise."""
+    d = getattr(base, "__dict__", None)
+    if isinstance(d, dict) and attr in d:
+        return True, d[attr]
+    try:
+        static = inspect.getattr_static(base, attr)
+    except Exception:
+        return False, None
+    if isinstance(static, (staticmethod, classmethod, property)):
+        return False, None
+    if (inspect.isfunction(static) or inspect.ismethoddescriptor(static)
+            or inspect.isdatadescriptor(static) or inspect.isbuiltin(static)):
+        return False, None
+    return True, static
+
+
+def _resolve_dotted(scope, dotted):
+    """(ok, value) of a dotted occurrence resolved from the captured frame
+    scope — the base must be a captured local, every hop must pass
+    _safe_attr_value."""
+    parts = dotted.split(".")
+    if parts[0] not in scope:
+        return False, None
+    obj = scope[parts[0]]
+    for seg in parts[1:]:
+        ok, obj = _safe_attr_value(obj, seg)
+        if not ok:
+            return False, None
+    return True, obj
+
+
+# Serializes snapshot workers: rapid menu-opens must not interleave two
+# publishes' shared bookkeeping on the same function.
+_snapshot_lock = threading.Lock()
+
+
+def publish_stack_locals(frames, extra_snapshots=None):
+    """The context-menu capture hook: publish every real caller frame's
+    locals into that function's live-value store (see publish_frame_snapshot).
+    ``frames`` is the raw get_live_frames output — entry[4] is the frame's
+    f_locals copy. ``extra_snapshots`` is a list of extra (fn, scope,
+    upto_lineno) publishes to run in the same batch (the capture site adds
+    the TARGET view function's entry scope).
+
+    Runs on a short-lived daemon worker: a first publish's site resolution
+    parses the enclosing span through libcst (one linemap per function,
+    cached per file-gen; a METHOD's span is its whole class) — far too heavy
+    for the render thread at menu-open. The store/watcher machinery is
+    worker-safe by design (the instrumented twin publishes from workers);
+    markers appear a beat after the menu via the normal watcher wake."""
+    threading.Thread(target=_publish_stack_locals_sync,
+                     args=(frames, extra_snapshots),
+                     name="lv-frame-snapshot", daemon=True).start()
+
+
+def _publish_stack_locals_sync(frames, extra_snapshots=None):
+    """Worker body of publish_stack_locals. Dispatch machinery and
+    non-project source are skipped, and a frame whose resolved function's
+    name doesn't match (lambdas, comprehensions) is dropped rather than
+    mis-published. Each item ALSO records its full scope's runtime types
+    into FuncsMetadata here (aliases like ds/value included — the anchored
+    publishes only cover source-bound names), so the capture site pays for
+    nothing but the stack grab itself. Best-effort per item — a resolution
+    hiccup must never break the batch."""
+    from meltygui.code.chain_converters import _is_dispatch_frame
+    from meltygui.code.chain_converters import _enclosing_function
+    from meltygui.code.fileref import is_editable_source
+    from meltygui.core.rendering.func_metadata import FuncsMetadata
+    with _snapshot_lock:
+        for entry in frames or ():
+            if len(entry) < 5 or not entry[4]:
+                continue
+            filename, lineno, func_name = entry[0], entry[1], entry[2]
+            try:
+                if (_is_dispatch_frame(filename, func_name)
+                        or not is_editable_source(filename)):
+                    continue
+                fn = _enclosing_function(filename, lineno)
+                if fn is None or getattr(fn, "__name__", None) != func_name:
+                    continue
+                FuncsMetadata.record(fn, entry[4])
+                publish_frame_snapshot(fn, entry[4], upto_lineno=lineno)
+            except Exception:
+                continue
+        for fn, scope, upto in extra_snapshots or ():
+            try:
+                FuncsMetadata.record(fn, scope)
+                publish_frame_snapshot(fn, scope, upto_lineno=upto)
+            except Exception:
+                continue
+
+
+def _stamp_delta(path, anchor_line):
+    """Stamp→pending line bridge. Line stamps (twin snapshot calls, editor
+    overlay lookups) are DISK-anchored — enclosing span's disk start +
+    pending-relative offset, the co_firstlineno invariant — while _ast_for's
+    tree is the PENDING text. The difference is the net shift of queued
+    edits fully above the enclosing def, so callers anchor at the DEF start
+    (co_firstlineno / the resolved function), never at the stamp itself: a
+    grown function's stamps can sit past its own span's disk end, which
+    would wrongly count the span's own edit into the delta."""
+    from meltygui.code.live_instrument import _delta_above
+    from meltygui.code.live_instrument import _pending_gen
+    if not _pending_gen(str(path)):
+        return 0
+    return _delta_above(str(path), anchor_line)
+
+
+def _resolve_site(code, lineno):
+    """The slow once-per-(code, line) path: locate the enclosing top-level
+    statement via ast, run the dict conversion on just that span, and derive
+    this call's key, the preceding assignment's name, and the store object.
+    Tree/LineMap lookups use pending coords (line_p); the store resolution
+    and the published line:N keys keep the raw DISK-anchored stamp — live
+    co_firstlineno values and the editor overlay both speak that
+    convention."""
+    from meltygui.code.chain_converters import _enclosing_function
+    from meltygui.code.chain_converters import _module_for_file
+
+    path = Path(code.co_filename).resolve()
+    mtime = path.stat().st_mtime
+    tree, text, sig = _ast_for(path, mtime)
+    line_p = lineno + _stamp_delta(
+        path, code.co_firstlineno
+        if code.co_flags & inspect.CO_OPTIMIZED else lineno)
+    var_name = _previous_assign_name(tree, line_p)
+
+    # A class body or method frame is not CO_OPTIMIZED; _enclosing_function
+    # would wrongly pick the nearest def ABOVE such a line (it has the end
+    # check), so only function frames attach to a function.
+    store_obj = None
+    store_is_module = True
+    if code.co_flags & inspect.CO_OPTIMIZED:
+        store_obj = _enclosing_function(code.co_filename, lineno)
+        store_is_module = store_obj is None
+    if store_obj is None:
+        store_obj = _module_for_file(path)
+
+    try:
+        loop_dims = _loop_dims_at(tree, line_p)
+    except Exception:
+        loop_dims = ()   # never let loop context kill site resolution
+
+    span = _top_level_span(tree, line_p)
+    lm = _linemap_for(path, sig, span, text)
+    arg_label = None
+
+    ref = _live_view_ref(lm, line_p)
+    if ref is not None:
+        key_path = _store_relative(ref.path, store_obj, store_is_module)
+        arg_label = _arg_source(ref.value)
+    else:
+        # The line isn't surfaced by a bare call: either it's an
+        # assignment form (y = live_view(x)`, keyed by its target - a real
+        # statement key, keep it) or it sits in a body the dict conversion
+        # doesn't extract (while/try/catch, nested def). The latter resolves
+        # to a CONTAINER, which would conflict across sites - qualify by line.
+        fallback = lm.node_at_line(line_p, absolute=True)
+        if fallback is not None:
+            full_path, call_node = _truncate_into_call(lm.root, fallback.path)
+            key_path = _store_relative(full_path, store_obj, store_is_module)
+            # arg_label means "the explicit live_view(expr) argument" - only a
+            # live_view call may supply it. The truncation cuts at ANY CallParse
+            # the path hits, so a snapshot stamp on `x = obj.method("lit")`
+            # lands here on the RHS call - reading ITS first arg produced a
+            # bogus label ('"lit"'), which also blocked _record_scope_type's
+            # trust-the-injected-name rule (arg_label must be None for stamps).
+            arg_label = (_arg_source(call_node)
+                         if _is_live_view_callparse(call_node) else None)
+            if (call_node is None and isinstance(fallback.value, dict)
+                    and fallback.span.start_line != line_p - lm.line_offset):
+                # The line landed in an enclosing CONTAINER (a while/with
+                # body the dict conversion doesn't surface) - that key would
+                # collide across every site in the block, so qualify by
+                # line. A hit whose statement STARTS at this line is the
+                # statement's bare entry - including a dict-VALUED assignment
+                # (`x = {...}`: value is a dict instance, but it's a call) -
+                # and keeps its clean statement key.
+                key_path = key_path + (f"line:{lineno}",)
+        else:
+            key_path = (f"line:{lineno}",)
+    if not key_path:
+        key_path = (f"line:{lineno}",)
+    if arg_label is None:
+        # No CallParse to read the arg from (un-surfaced body) - use the ast.
+        arg_label = _arg_source_ast(tree, line_p)
+    return _Site(key_path, var_name, arg_label, store_obj, lineno, loop_dims)
+
+
+def _loop_dims_at(tree, lineno):
+    """Auto dim names of the loops enclosing `lineno`, outermost first,
+    within the line's innermost frame scope — a def/class boundary resets
+    the chain (its body publishes from a different frame, so outer loops
+    don't repeat ITS sites). Only a loop's BODY iterates: a line in its
+    `else:` runs once and is not counted, and the header line itself
+    (`for x in live_view(seq):`) contributes nothing."""
+    dims, body = [], tree.body
+    while True:
+        stmt = next(
+            (s for s in body
+             if s.lineno <= lineno <= getattr(s, "end_lineno", s.lineno)),
+            None)
+        if stmt is None:
+            return tuple(dims)
+        if isinstance(stmt, (ast.FunctionDef, ast.AsyncFunctionDef,
+                             ast.ClassDef)):
+            dims = []
+        next_body = None
+        for block, iterates in _stmt_blocks(stmt):
+            if any(s.lineno <= lineno <= getattr(s, "end_lineno", s.lineno)
+                   for s in block):
+                if iterates:
+                    dims.append(_loop_name(stmt))
+                next_body = block
+                break
+        if next_body is None:
+            return tuple(dims)
+        body = next_body
+
+
+def _stmt_blocks(stmt):
+    """(statement block, iterates) pairs for every block of `stmt` — only a
+    For/While `body` iterates."""
+    is_loop = isinstance(stmt, (ast.For, ast.AsyncFor, ast.While))
+    for field in _BODY_FIELDS:
+        sub = getattr(stmt, field, None)
+        if isinstance(sub, list) and sub:
+            yield sub, is_loop and field == "body"
+    for handler in getattr(stmt, "handlers", None) or []:
+        yield handler.body, False
+    for case in getattr(stmt, "cases", None) or []:
+        yield case.body, False
+
+
+def _loop_name(stmt):
+    """The auto dim name for one loop: the first plain Name in a for-target
+    ('i' for `for i, layer in enumerate(…)` — the index var by position),
+    'iter' for a while (no target to name it by)."""
+    target = getattr(stmt, "target", None)
+    if target is not None:
+        for node in ast.walk(target):
+            if isinstance(node, ast.Name):
+                return node.id
+    return "iter"
+
+
+def _ast_for(path, mtime):
+    """(tree, text, sig) of the file's IN-MEMORY source — disk with every
+    queued (unsaved) span edit spliced in (PendingSave.current_file_text:
+    the same text the twin and Ctrl+Enter's hotswap compile). live_view must
+    never parse raw disk text: deferred saves leave disk stale mid-session,
+    and resolving keys against the pre-edit layout is exactly the
+    adjacent-line key jumbling / bare line:N fallback bug. Cache signature =
+    (mtime, pending gen) — both cheap; the O(file) splice runs on miss
+    only."""
+    from meltygui.code.live_instrument import _pending_gen
+    key = str(path)
+    gen = _pending_gen(key)
+    sig = (mtime, gen)
+    cached = _asts.get(key)
+    if cached is not None and cached[0] == sig:
+        return cached[1], cached[2], sig
+    text = None
+    if gen:
+        from meltygui.editor.pending_save import PendingSave
+        text = PendingSave.current_file_text(path)
+    if text is None:
+        text = path.read_text()
+    _t0 = time.perf_counter()
+    tree = ast.parse(text)
+    try:  # TEMP perf: how often the full-file reparse actually fires
+        from meltygui.core.diagnostics.perf_trace import trace as _pt
+        _pt("live_view ast reparse", path=path.name, gen=gen,
+            ms=round((time.perf_counter() - _t0) * 1000.0, 1))
+    except Exception:
+        pass
+    _asts[key] = (sig, tree, text)
+    return tree, text, sig
+
+
+def _top_level_span(tree, lineno):
+    """(start, end) 1-indexed file lines of the top-level statement containing
+    `lineno` — the def/class (decorators included) whose span the dict
+    conversion runs on. None when no statement contains the line."""
+    for stmt in tree.body:
+        end = getattr(stmt, "end_lineno", stmt.lineno)
+        start = min([stmt.lineno] + [d.lineno for d in
+                                     getattr(stmt, "decorator_list", [])])
+        if start <= lineno <= end:
+            return start, end
+    return None
+
+
+def _linemap_for(path, sig, span, text):
+    """The LineMap of one top-level statement's span (whole file when span is
+    None), rebuilt when `sig` — _ast_for's (mtime, pending gen) — changes,
+    so queued edits that never touch disk still invalidate. Span-bounded so
+    a save re-parses one function, not the file — the whole-file position
+    pass holds the GIL for ~1s on big modules (see chain_converters'
+    measurement) and this runs on the calling thread."""
+    import libcst as cst
+    from meltygui.code.libcst_conversion import LineMap
+    from meltygui.code.libcst_conversion import cst_module_to_dict
+
+    start = span[0] if span else 1
+    key = (str(path), start)
+    cached = _linemaps.get(key)
+    if cached is not None and cached[0] == sig:
+        return cached[1]
+    if span is None:
+        snippet = text
+    else:
+        lines = text.splitlines(keepends=True)
+        snippet = "".join(lines[span[0] - 1:span[1]])
+    from meltygui.core.runtime.toggles import Toggles
+    if Toggles.TextEditor.melty_syntax:
+        parse = cst_module_to_dict(snippet)                 # core_syntax (raw input)
+    else:
+        parse = cst_module_to_dict(cst.parse_module(snippet))
+    lm = LineMap(parse, line_offset=start - 1)
+    _linemaps[key] = (sig, lm)
+    return lm
+
+
+def _live_view_ref(lm, lineno):
+    """The NodeRef of the live_view CALL whose span contains `lineno` — matched
+    by key, not node_at_line, because the deepest node at the line is usually
+    an ARG inside the CallParse. Deepest match wins. (Reads LineMap's _entries
+    index directly — in-package machinery, same data node_at_line scans.)"""
+    rel_line = lineno - lm.line_offset
+    best = None
+    for span, depth, ref in lm._entries:
+        if not (span.start_line <= rel_line <= span.end_line):
+            continue
+        if not isinstance(ref.key, str):
+            continue
+        if ref.key.split("#", 1)[0] != "live_view()":
+            continue
+        if best is None or depth > best[0]:
+            best = (depth, ref)
+    return best[1] if best else None
+
+
+def _truncate_into_call(root, path):
+    """Cut `path` segments that descend INSIDE a call's argument dict — the
+    statement key is the site's address; which argument the line landed on is
+    not. Returns (path, call_parse) where call_parse is the CallParse the path
+    was cut at (None if the path never enters one)."""
+    from meltygui.code.libcst_conversion import CallParse
+    node = root
+    for i, seg in enumerate(path):
+        node = node.get(seg) if isinstance(node, dict) else None
+        if isinstance(node, CallParse):
+            return tuple(path[:i + 1]), node
+        if node is None:
+            break
+    return tuple(path), None
+
+
+def _owning_def_name(path):
+    """The name of the innermost def a key path crosses (`..., <name>,
+    "locals", ...`), or None for module/class-level paths."""
+    for i in range(len(path) - 1, 0, -1):
+        if path[i] == "locals":
+            return path[i - 1]
+    return None
+
+
+def _store_relative(path, store_obj, store_is_module):
+    """Key path relative to the STORE OBJECT's scope. For a function store,
+    cut at the first `<func name>, "locals"` pair — nested-def segments stay,
+    so two closures' sites on the same outer function can't collide, and the
+    editor parsing that function's span sees the same paths. Module stores
+    keep the full path."""
+    if store_is_module:
+        return tuple(path)
+    fn_name = getattr(store_obj, "__name__", None)
+    for i in range(len(path) - 1):
+        if path[i] == fn_name and path[i + 1] == "locals":
+            return tuple(path[i + 2:])
+    # Renamed wrapper / span mismatch: fall back to the innermost scope cut.
+    for i in range(len(path) - 1, -1, -1):
+        if path[i] == "locals":
+            return tuple(path[i + 1:])
+    return tuple(path)
+
+
+def _is_live_view_callparse(call_parse):
+    """True when a CallParse is a `live_view(...)` call. Guards arg_label
+    resolution: the statement-path truncation cuts at whatever CallParse it
+    enters first, which for a snapshot-stamped assignment is the RHS's own
+    call — whose arguments have nothing to do with live_view's."""
+    if not isinstance(call_parse, dict):
+        return False
+    func_name = getattr(call_parse, "func_name", None)    # CallParse, either form
+    if isinstance(func_name, str):
+        return func_name.rsplit(".", 1)[-1] == "live_view"
+    try:
+        func = call_parse.get("__cst__").func
+    except Exception:
+        return False
+    name = getattr(func, "value", None)          # cst.Name
+    if not isinstance(name, str):
+        name = getattr(getattr(func, "attr", None), "value", None)  # cst.Attribute
+    return name == "live_view"
+
+
+def _arg_source(call_parse):
+    """The source text of an explicit `live_view(expr)` argument, for display.
+    The positional arg binds to live_view's `value` parameter when the
+    signature resolves, else surfaces under a synthetic `arg0` key — take the
+    first real entry either way."""
+    if not isinstance(call_parse, dict):
+        return None
+    arg = call_parse.get("value")
+    if arg is None:
+        for k, v in call_parse.items():
+            if isinstance(k, str) and not k.startswith("__"):
+                arg = v
+                break
+    return str(arg) if arg is not None else None
+
+
+# ── previous-assignment resolution (ast) ──────────────────────────────────────
+# The display dict drops statements it can't surface (aug-assigns, tuple
+# unpacks, while/with/match bodies), so walking its keys silently skips them
+# and captures an OLDER variable. The ast sees every statement; resolve the
+# bare form against it instead.
+
+def _previous_assign_name(tree, lineno):
+    """The variable assigned by the statement preceding the live_view call at
+    `lineno`: locate the deepest body list holding the call's statement, walk
+    its preceding siblings backwards, and take the first assignment target —
+    descending into a preceding block's last assignment, skipping defs."""
+    found = _stmt_in_body(tree.body, lineno)
+    if found is None:
+        return None
+    body, idx = found
+    for stmt in reversed(body[:idx]):
+        name = _direct_target(stmt)
+        if name is _STOP:
+            # The preceding statement DOES bind something we can't name (tuple
+            # unpack, obj.attr / a[i] target) - publishing an older variable
+            # instead would be silently losing data. Capture nothing.
+            return None
+        if name is not None:
+            return name
+        name = _last_target(stmt)  # blocks capture their last assignment
+        if name is not None:
+            return name
+    return None
+
+
+_BODY_FIELDS = ("body", "orelse", "finalbody")
+
+
+def _stmt_in_body(body, lineno):
+    """(body list, index) of the statement containing a live_view call at
+    `lineno`, in the DEEPEST body list that holds it."""
+    for i, stmt in enumerate(body):
+        end = getattr(stmt, "end_lineno", stmt.lineno)
+        if not (stmt.lineno <= lineno <= end):
+            continue
+        for field in _BODY_FIELDS:
+            sub = getattr(stmt, field, None)
+            if isinstance(sub, list) and sub:
+                found = _stmt_in_body(sub, lineno)
+                if found is not None:
+                    return found
+        for handler in getattr(stmt, "handlers", None) or []:
+            found = _stmt_in_body(handler.body, lineno)
+            if found is not None:
+                return found
+        for case in getattr(stmt, "cases", None) or []:
+            found = _stmt_in_body(case.body, lineno)
+            if found is not None:
+                return found
+        if _holds_live_view_call(stmt):
+            return body, i
+        return None
+    return None
+
+
+def _arg_source_ast(tree, lineno):
+    """The explicit argument's source for a live_view call at `lineno`, read
+    from the ast — the label fallback for calls in bodies the dict conversion
+    doesn't surface (while/with/match, nested defs)."""
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.Call) or not node.args:
+            continue
+        end = getattr(node, "end_lineno", node.lineno)
+        if not (node.lineno <= lineno <= end):
+            continue
+        func = node.func
+        name = (func.id if isinstance(func, ast.Name)
+                else func.attr if isinstance(func, ast.Attribute) else None)
+        if name == "live_view":
+            return ast.unparse(node.args[0])
+    return None
+
+
+def _holds_live_view_call(stmt):
+    for node in ast.walk(stmt):
+        if isinstance(node, ast.Call):
+            func = node.func
+            name = (func.id if isinstance(func, ast.Name)
+                    else func.attr if isinstance(func, ast.Attribute) else None)
+            if name == "live_view":
+                return True
+    return False
+
+
+_STOP = object()
+
+
+def _direct_target(stmt):
+    """A direct assignment's target name; _STOP for an assignment whose target
+    can't be named as a frame local (tuple unpack, obj.attr, a[i]); None for a
+    non-binding statement (defs and classes bind names whose body locals are
+    not in the caller's frame — non-binding here)."""
+    if isinstance(stmt, ast.Assign):
+        for target in stmt.targets:  # p = q = v → the first plain-name target
+            if isinstance(target, ast.Name):
+                return target.id
+        return _STOP
+    if isinstance(stmt, (ast.AugAssign, ast.AnnAssign)):
+        return stmt.target.id if isinstance(stmt.target, ast.Name) else _STOP
+    return None
+
+
+def _last_target(stmt):
+    """The LAST direct assignment name anywhere inside a block statement, in
+    source order — what a bare live_view right after an if/for/try captures."""
+    last = None
+    direct = _direct_target(stmt)
+    if direct is not None:
+        return direct if direct is not _STOP else None
+    if isinstance(stmt, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+        return None
+    for field in _BODY_FIELDS:
+        for sub in getattr(stmt, field, None) or []:
+            name = _last_target(sub)
+            if name is not None:
+                last = name
+    for handler in getattr(stmt, "handlers", None) or []:
+        for sub in handler.body:
+            name = _last_target(sub)
+            if name is not None:
+                last = name
+    return last
+
+
+def publish_external_values(filename, source, name, values):
+    """Attach project-process snapshots to the same owner the inline UI reads.
+
+    Only a no-op function is compiled locally: project imports, decorators,
+    defaults and user code belong exclusively to the project interpreter.
+    Values are (source line, variable name, decoded value) triples.
+    """
+    import hashlib
+    from meltygui.code import chain_converters as cc
+    from meltygui.code.live_instrument import _delta_above
+
+    path = Path(filename).resolve()
+    node = next(n for n in ast.parse(source).body
+                if isinstance(n, (ast.FunctionDef, ast.AsyncFunctionDef)) and n.name == name)
+    start = min([node.lineno] + [d.lineno for d in node.decorator_list])
+    delta = _delta_above(str(path), start)
+    delta = _delta_above(str(path), max(1, start - delta))
+    disk_start = max(1, node.lineno - delta)
+    modules = cc._modules_for_file(path)
+    if modules:
+        module = modules[0]
+    else:
+        module_name = '_melty_fnrun_' + hashlib.sha256(str(path).encode()).hexdigest()
+        module = types.ModuleType(module_name)
+        module.__file__ = str(path)
+        sys.modules[module_name] = module
+    slot = f'_fnrun_live_{name}'
+    previous = vars(module).get(slot)
+    namespace = {'__name__': module.__name__}
+    exec(compile('\n' * (disk_start - 1) + f'def {name}():\n    pass\n',
+                 str(path), 'exec'), namespace)
+    owner = namespace[name]
+    owner.__fnrun_exec__ = True
+    adopt_live_store(previous, owner)
+    vars(module)[slot] = owner
+    for key in list(cc._ENCLOSING_FN_CACHE):
+        if key[0] == str(path):
+            del cc._ENCLOSING_FN_CACHE[key]
+    with run_capture(owner):
+        for line, label, value in values:
+            disk_line = line - delta
+            site = _Site((f'line:{disk_line}#{label}',), None, None, owner, disk_line)
+            _publish(site, value, label, bare=False)
+    return owner