meltygui 0.1.0__py3-none-any.whl

meltygui/core/rendering/render_funcs.py

@@ -0,0 +1,273 @@
+"""Symbol access to @render_func renderers without importing their module.
+
+`RenderFuncs.draw_type` returns a lazy handle that resolves at call time from the
+render-func registry (auto-populated by the @render_func decorator). This
+sidesteps import cycles: referencing a render func here never triggers an import
+of whatever heavy module defines it.
+
+This module never imports Melty — the dependency runs the other way. Melty owns
+and manages the registry; we reach it through the lightweight Core.melty handle
+so that referencing render funcs stays a low-level concern, not one that reaches
+back up into the Melty hub.
+
+CodeGenerator regenerates the _RenderFuncs class in THIS file so every registered
+render func shows up as a real, IDE-visible member — kept in its own file so the
+generator only ever rewrites this small module, never meltygui.py.
+"""
+from meltygui.core.rendering.core_decoration import Core
+
+
+class _LazyRenderFunc:
+    """A by-name handle to a @render_func, resolved on first use.
+
+    Behaves like the render func itself: callable with the same signature and
+    carrying the right __name__ (the view system reads that). Resolution is
+    deferred to call time, by which point every module has imported and
+    self-registered into the registry (reached via Core.melty) — so referencing
+    one of these never triggers an import and never participates in an import cycle.
+    """
+
+    __slots__ = ("__name__", "_fn")
+
+    def __init__(self, name):
+        self.__name__ = name
+        self._fn = None
+
+    def _resolve(self):
+        # Always re-read the registry - never serve a pinned static resolution.
+        # A recompile/hotload re-registers the name (and the reconcile pass
+        # redirected the entry point at the live wrapper, see
+        # _redirect_function_registrations); a static cache here would pin
+        # whatever object happened to be registered at first call and keep
+        # serving its stale address after later recompiles. One dict get per call
+        # is noise next to a render. _fn exists only as a fallback for a
+        # transient gap (mid-recompile) where the name is momentarily missing.
+        fn = Core.melty.render_funcs_by_name.get(self.__name__)
+        if fn is not None:
+            self._fn = fn
+            return fn
+        if self._fn is not None:
+            return self._fn
+        print(f"Registered render funcs: {list(Core.melty.render_funcs_by_name)}")
+        raise AttributeError(
+            f"No @render_func named {self.__name__!r} is registered")
+
+    def __call__(self, *args, **kwargs):
+        return self._resolve()(*args, **kwargs)
+
+    def __getattr__(self, item):
+        # Forward real attributes (e.g. _load_data/_save_data) to the resolved
+        # func, but never dunders; copy/pickle probes (__deepcopy__, etc.) must
+        # fall through to default handling rather than force early resolution.
+        if item.startswith("__") and item.endswith("__"):
+            raise AttributeError(item)
+        return getattr(self._resolve(), item)
+
+
+class _RenderFuncs:
+    """`RenderFuncs.draw_type` -> a _LazyRenderFunc handle, no import required.
+
+    The members below are generated by CodeGenerator (one per registered
+    @render_func) so IDEs autocomplete RenderFuncs.<name>. Each is a real class
+    attribute; __getattr__ is the fallback for any render func added since the
+    last regeneration. Regenerate via CodeGenerator.update_render_funcs().
+    """
+    draw_view_func_selector = _LazyRenderFunc("draw_view_func_selector")
+    _do_save = _LazyRenderFunc("_do_save")
+    address_to_call_parse = _LazyRenderFunc("address_to_call_parse")
+    address_to_class = _LazyRenderFunc("address_to_class")
+    address_to_function = _LazyRenderFunc("address_to_function")
+    address_to_general_parse = _LazyRenderFunc("address_to_general_parse")
+    address_to_module = _LazyRenderFunc("address_to_module")
+    button = _LazyRenderFunc("button")
+    call_dict_to_save = _LazyRenderFunc("call_dict_to_save")
+    caller_to_address = _LazyRenderFunc("caller_to_address")
+    chain_cls_load = _LazyRenderFunc("chain_cls_load")
+    class_to_address = _LazyRenderFunc("class_to_address")
+    class_to_address_incl_overrides = _LazyRenderFunc("class_to_address_incl_overrides")
+    class_to_var_dict = _LazyRenderFunc("class_to_var_dict")
+    cls_to_cst = _LazyRenderFunc("cls_to_cst")
+    cst_to_address = _LazyRenderFunc("cst_to_address")
+    cst_to_cls = _LazyRenderFunc("cst_to_cls")
+    cst_to_fn = _LazyRenderFunc("cst_to_fn")
+    cst_to_mod = _LazyRenderFunc("cst_to_mod")
+    cst_to_ref = _LazyRenderFunc("cst_to_ref")
+    dict_to_cst = _LazyRenderFunc("dict_to_cst")
+    do_recompile = _LazyRenderFunc("do_recompile")
+    draw_blank = _LazyRenderFunc("draw_blank")
+    draw_bool = _LazyRenderFunc("draw_bool")
+    draw_collection = _LazyRenderFunc("draw_collection")
+    draw_collection_as_tabs = _LazyRenderFunc("draw_collection_as_tabs")
+    draw_comment = _LazyRenderFunc("draw_comment")
+    draw_context_menu = _LazyRenderFunc("draw_context_menu")
+    draw_debug_label = _LazyRenderFunc("draw_debug_label")
+    draw_drag_drop_target = _LazyRenderFunc("draw_drag_drop_target")
+    draw_draw_state = _LazyRenderFunc("draw_draw_state")
+    draw_draw_state_info = _LazyRenderFunc("draw_draw_state_info")
+    draw_drop_down_item = _LazyRenderFunc("draw_drop_down_item")
+    draw_dropdown = _LazyRenderFunc("draw_dropdown")
+    draw_enum = _LazyRenderFunc("draw_enum")
+    draw_enum_tabs = _LazyRenderFunc("draw_enum_tabs")
+    draw_float = _LazyRenderFunc("draw_float")
+    draw_float_ctx = _LazyRenderFunc("draw_float_ctx")
+    draw_function = _LazyRenderFunc("draw_function")
+    draw_int = _LazyRenderFunc("draw_int")
+    draw_jump_to = _LazyRenderFunc("draw_jump_to")
+    draw_managed_window = _LazyRenderFunc("draw_managed_window")
+    draw_mapping_proxy = _LazyRenderFunc("draw_mapping_proxy")
+    draw_module = _LazyRenderFunc("draw_module")
+    draw_none = _LazyRenderFunc("draw_none")
+    draw_parameter = _LazyRenderFunc("draw_parameter")
+    draw_pending = _LazyRenderFunc("draw_pending")
+    draw_pending_texture = _LazyRenderFunc("draw_pending_texture")
+    draw_property = _LazyRenderFunc("draw_property")
+    draw_search = _LazyRenderFunc("draw_search")
+    draw_single = _LazyRenderFunc("draw_single")
+    draw_str = _LazyRenderFunc("draw_str")
+    draw_style_manager = _LazyRenderFunc("draw_style_manager")
+    draw_tab_bar = _LazyRenderFunc("draw_tab_bar")
+    draw_tensor = _LazyRenderFunc("draw_tensor")
+    draw_text = _LazyRenderFunc("draw_text")
+    draw_texture = _LazyRenderFunc("draw_texture")
+    draw_tint_context = _LazyRenderFunc("draw_tint_context")
+    draw_tuple = _LazyRenderFunc("draw_tuple")
+    draw_type = _LazyRenderFunc("draw_type")
+    draw_usage = _LazyRenderFunc("draw_usage")
+    draw_with_modes = _LazyRenderFunc("draw_with_modes")
+    empty = _LazyRenderFunc("empty")
+    eval_function = _LazyRenderFunc("eval_function")
+    fn_to_cst = _LazyRenderFunc("fn_to_cst")
+    focus = _LazyRenderFunc("focus")
+    function_to_address = _LazyRenderFunc("function_to_address")
+    general_parse_to_address = _LazyRenderFunc("general_parse_to_address")
+    general_parse_to_str = _LazyRenderFunc("general_parse_to_str")
+    load_cst_module = _LazyRenderFunc("load_cst_module")
+    mod_to_cst = _LazyRenderFunc("mod_to_cst")
+    module_to_address = _LazyRenderFunc("module_to_address")
+    parse_source_to_general = _LazyRenderFunc("parse_source_to_general")
+    path_to_address = _LazyRenderFunc("path_to_address")
+    pending_window = _LazyRenderFunc("pending_window")
+    recompile_caller_fn = _LazyRenderFunc("recompile_caller_fn")
+    recompile_cls_fn = _LazyRenderFunc("recompile_cls_fn")
+    recompile_fn = _LazyRenderFunc("recompile_fn")
+    recompile_mod_fn = _LazyRenderFunc("recompile_mod_fn")
+    ref_to_cst = _LazyRenderFunc("ref_to_cst")
+    rf_address_to_dict = _LazyRenderFunc("rf_address_to_dict")
+    rf_bytes_to_str = _LazyRenderFunc("rf_bytes_to_str")
+    rf_dict_to_address = _LazyRenderFunc("rf_dict_to_address")
+    rf_dict_to_path = _LazyRenderFunc("rf_dict_to_path")
+    rf_dict_to_str = _LazyRenderFunc("rf_dict_to_str")
+    rf_path_to_bytes = _LazyRenderFunc("rf_path_to_bytes")
+    rf_path_to_dict = _LazyRenderFunc("rf_path_to_dict")
+    rf_str_to_bytes = _LazyRenderFunc("rf_str_to_bytes")
+    rf_str_to_dict = _LazyRenderFunc("rf_str_to_dict")
+    run_button = _LazyRenderFunc("run_button")
+    run_chain = _LazyRenderFunc("run_chain")
+    save_file_fn = _LazyRenderFunc("save_file_fn")
+    save_span_fn = _LazyRenderFunc("save_span_fn")
+    str_to_general_parse = _LazyRenderFunc("str_to_general_parse")
+    test_columns = _LazyRenderFunc("test_columns")
+    test_widget = _LazyRenderFunc("test_widget")
+    text = _LazyRenderFunc("text")
+    unsort_dict_alphabetically = _LazyRenderFunc("unsort_dict_alphabetically")
+    var_dict_to_class = _LazyRenderFunc("var_dict_to_class")
+
+    def __getattr__(self, name):
+        # Dunders must NOT fabricate or handle. No render func is named like a
+        # dunder, and fabricating would break copy/pickle of anything holding
+        # RenderFuncs (deepcopy probes __deepcopy__ -> a _LazyRenderFunc whose
+        # _resolve() raises + spams the registry to stdout) and would detonate
+        # inspect.unwrap the moment _LazyRenderFunc gains a __class__ property.
+        # See _LazyRenderFunc.__getattr__'s own guard (and _Modes in modes.py).
+        if name.startswith("__") and name.endswith("__"):
+            raise AttributeError(name)
+        return _LazyRenderFunc(name)
+
+
+
+# Reference render funcs by symbol without importing their module:
+#     from meltygui.core.rendering.render_funcs import RenderFuncs
+#     @window(render_func=RenderFuncs.draw_type)
+RenderFuncs = _RenderFuncs()
+
+
+class CodeGenerator:
+    """Headless code generation over the app's own cst↔dict round-trip.
+
+    update_render_funcs() rewrites the _RenderFuncs class above so every
+    registered @render_func shows up as a real, IDE-visible member — that's what
+    makes `RenderFuncs.<name>` autocomplete. The edit runs through the same
+    converters the in-app editor uses, just without imgui:
+
+        source span → cst.ClassDef → cst_classdef_to_dict → (add a key per name)
+                    → dict_to_cst_classdef → source span
+
+    Each member is a real assignment (`name = _LazyRenderFunc("name")` /
+    `name = _LazyMode("name")`), so it is a genuine class attribute the IDE can
+    see; __getattr__ stays as the fallback for anything added since the last
+    regeneration. Nothing to recompile or hotswap — runtime behaviour is unchanged.
+    """
+
+    @staticmethod
+    def _regenerate(target_cls, names, expr_for):
+        """Rewrite `target_cls`'s body in this file so it has one assignment per
+        name, via the same cst↔dict round-trip the in-app editor uses:
+
+            source span → cst.ClassDef → cst_classdef_to_dict → (add a key per
+                        name) → dict_to_cst_classdef → source span
+
+        Existing class vars are stripped first so only the Add path runs (clean +
+        idempotent). `expr_for(name)` returns the assignment's RHS source.
+        Returns the written Address."""
+        import libcst as cst
+        from meltygui.code.fileref import to_address
+        from meltygui.code.file_converters import load_text
+        from meltygui.code.file_converters import save_span_fn
+        from meltygui.code.libcst_conversion import cst_classdef_to_dict
+        from meltygui.code.libcst_conversion import dict_to_cst_classdef
+
+        class _StripClassVars(cst.CSTTransformer):
+            def leave_SimpleStatementLine(self, original, updated):
+                if len(updated.body) == 1 and isinstance(
+                        updated.body[0], (cst.Assign, cst.AnnAssign)):
+                    return cst.RemoveFromParent()
+                return updated
+
+        ref = to_address(target_cls)
+        if ref is None:
+            raise RuntimeError(
+                f"Could not resolve the source location of {target_cls.__name__}")
+
+        module = cst.parse_module(load_text(ref))
+        classdef = next(s for s in module.body if isinstance(s, cst.ClassDef))
+        classdef = classdef.visit(_StripClassVars())
+
+        members = cst_classdef_to_dict(classdef)
+        for name in names:
+            members[name] = cst.parse_expression(expr_for(name))
+        new_classdef = dict_to_cst_classdef(members)
+
+        new_module = module.with_changes(body=[
+            new_classdef if isinstance(s, cst.ClassDef) else s for s in module.body])
+
+        # save_span_fn is a @render_func; .__wrapped__ is the bare span-spelle
+        # (no imgui / draw_state) - the headless edge of the same save node the
+        # in-app editor saves through.
+        save_span_fn.__wrapped__(new_module.code, ref=ref)
+        return ref
+
+    @staticmethod
+    def update_render_funcs():
+        """Regenerate _RenderFuncs from the live @render_func registry."""
+        names = sorted(n for n in Core.melty.render_funcs_by_name if n.isidentifier())
+        return CodeGenerator._regenerate(
+            _RenderFuncs, names, lambda n: f'_LazyRenderFunc("{n}")')
+
+    @staticmethod
+    def update_modes():
+        """Regenerate _Modes (in modes.py) from the live Mode enum."""
+        from meltygui.core.rendering.mode import Mode
+        from meltygui.core.rendering.modes import _Modes
+        names = sorted(n for n in Mode.__members__ if n.isidentifier())
+        return CodeGenerator._regenerate(
+            _Modes, names, lambda n: f'_LazyMode("{n}")')

meltygui/core/rendering/shaped.py

@@ -0,0 +1,312 @@
+"""Shape-refined default routing: `Shaped(of, shape, dtype)`.
+
+`is_default_for` / `is_lens_for` route a value to a view by its TYPE or type
+NAME. A `Shaped` entry refines that by the value's SHAPE (and optionally its
+dtype), so "tuples of 3 floats" and "tensors with 3+ dims" are both one
+registration:
+
+    @render_func(is_default_for=('tint', Shaped(tuple, (3,), float),
+                                         Shaped(tuple, (4,), float)))
+    @render_func(is_default_for=(Shaped("Tensor", (None, None)),))          # 2-D
+    @render_func(is_default_for=("GLTexture", Shaped("Tensor", (None, None, None, ...))))
+
+The unifying idea: every value has a signature `(type, shape, dtype)` and a
+tuple is a tiny 1-D tensor — `(0.2, 0.5, 1.0)` is `(tuple, (3,), float)`,
+`torch.randn(8, 64, 64)` is `(Tensor, (8, 64, 64), float)`. One pattern
+grammar covers both.
+
+Shape PATTERN grammar — plain tuples, Python's own shape idiom:
+
+    3          this axis has extent exactly 3
+    None       this axis has any extent                  (TensorShape([None, 3]))
+    ...        any number of further axes; must be LAST  (tuple[int, ...])
+    {3, 4}     this axis has one of these extents
+
+    (3,)                      len-3 tuple / 1-D tensor of 3
+    (None, None)              exactly 2-D
+    (None, None, None, ...)   3-D or more
+    ({3, 4},)                 len 3 or 4
+
+`dtype` is a Python KIND — `float`, `int`, `bool`, `complex` — or a tuple of
+kinds (any-of), or None (don't care). Tensor/ndarray dtypes map to their kind
+(bf16/f16/f32/f64 → float, every int width → int). A SEQUENCE's dtype is its
+PROMOTED kind, like torch.result_type: any float present → float, all ints →
+int, all bools → bool, anything else (str, nested, mixed) → None. So
+`Shaped(tuple, (3,), float)` takes `(0, 0, 0, 0.1)` (a real tint) but not
+`(1, 2, 3)` (a version / int triple), which keeps int positions and extents
+off the colour picker.
+
+Cost contract: shape extraction is O(1) — `.shape` on tensors, `len()` on
+sequences. The only O(n) step is the sequence dtype promotion and it runs ONLY
+after the shape pattern already matched (so the pattern bounds n) and never
+past `SEQ_DTYPE_SCAN_CAP` elements (dtype = None beyond it). No value-RANGE
+constraints on purpose: they'd be an O(content) scan on tensors.
+
+Precedence among Shaped entries is by `score()`: the more constrained pattern
+wins (fixed axis 2, `None` axis 1, `...` 0, dtype +1), so a generic
+`(None,)` never steals a `(3,), float` colour. Ties → closer MRO match →
+registration order. This module is dependency-free so it can be imported from
+anywhere (registrations live in view modules; resolution lives in meltygui).
+"""
+from dataclasses import dataclass
+from typing import Any, Iterable, Optional
+
+# Sequences longer than this never get a dtype (pattern-matched first, so only
+# an unbounded `(None,)`/`(...)` pattern can reach it).
+SEQ_DTYPE_SCAN_CAP = 64
+
+_KINDS = (float, int, bool, complex)
+
+
+def _freeze_axis(axis):
+    if axis is None or axis is Ellipsis:
+        return axis
+    if isinstance(axis, bool):
+        raise TypeError(f"shape axis must be int/None/.../set, got bool {axis!r}")
+    if isinstance(axis, int):
+        if axis < 0:
+            raise ValueError(f"shape axis extent must be >= 0, got {axis}")
+        return axis
+    if isinstance(axis, (set, frozenset, list, tuple)):
+        members = frozenset(axis)
+        if not members or any(not isinstance(m, int) or isinstance(m, bool) or m < 0
+                              for m in members):
+            raise TypeError(f"one-of axis must hold non-negative ints, got {axis!r}")
+        return members
+    raise TypeError(f"unsupported shape axis {axis!r}")
+
+
+@dataclass(frozen=True)
+class Shaped:
+    """A (type, shape-pattern, dtype) matcher. Hashable → usable as a registry
+    key alongside plain types / type names in `is_default_for`."""
+    of: Any                        # type or type NAME ("Tensor", "ndarray")
+    shape: tuple                   # pattern, see module doc
+    dtype: Any = None              # kind, tuple of kinds, or None
+
+    def __post_init__(self):
+        if not isinstance(self.of, (type, str)):
+            raise TypeError(f"Shaped.of must be a type or a type name, got {self.of!r}")
+        if isinstance(self.shape, (int, type(None))):
+            shape = (self.shape,)
+        else:
+            shape = tuple(self.shape)
+        shape = tuple(_freeze_axis(a) for a in shape)
+        if Ellipsis in shape[:-1]:
+            raise ValueError("`...` may only appear as the LAST axis of a shape pattern")
+        object.__setattr__(self, "shape", shape)
+        dtype = self.dtype
+        if dtype is not None:
+            kinds = tuple(dtype) if isinstance(dtype, (tuple, list, set, frozenset)) else (dtype,)
+            for k in kinds:
+                if k not in _KINDS:
+                    raise TypeError(f"Shaped.dtype must be one of {_KINDS}, got {k!r}")
+            object.__setattr__(self, "dtype", kinds if len(kinds) > 1 else kinds[0])
+
+    # -- display ---------------------------------------------------------
+    def __repr__(self):
+        of = self.of.__name__ if isinstance(self.of, type) else repr(self.of)
+        axes = []
+        for a in self.shape:
+            if a is Ellipsis:
+                axes.append("...")
+            elif isinstance(a, frozenset):
+                axes.append("{" + ", ".join(str(m) for m in sorted(a)) + "}")
+            else:
+                axes.append(str(a))
+        shape = "(" + ", ".join(axes) + ("," if len(axes) == 1 else "") + ")"
+        if self.dtype is None:
+            return f"Shaped({of}, {shape})"
+        dt = self.dtype
+        dt = ("(" + ", ".join(k.__name__ for k in dt) + ")") if isinstance(dt, tuple) else dt.__name__
+        return f"Shaped({of}, {shape}, {dt})"
+
+    # -- matching --------------------------------------------------------
+    @property
+    def score(self) -> int:
+        """Constraint strength; higher = more specific. Fixed / one-of axis 2,
+        `None` axis 1 (still pins ndim), `...` 0, dtype +1."""
+        s = 0
+        for a in self.shape:
+            if a is Ellipsis:
+                continue
+            s += 1 if a is None else 2
+        if self.dtype is not None:
+            s += 1
+        return s
+
+    def matches_type(self, real_type: type) -> int:
+        """MRO distance of the closest class matching `of` (0 = exact), or -1."""
+        return mro_distance(self.of, real_type)
+
+    def matches_shape(self, shape) -> bool:
+        return shape is not None and shape_matches(self.shape, shape)
+
+    def matches_dtype(self, value) -> bool:
+        if self.dtype is None:
+            return True
+        kind = value_dtype(value)
+        if kind is None:
+            return False
+        return kind in self.dtype if isinstance(self.dtype, tuple) else kind is self.dtype
+
+    def matches(self, value, real_type: Optional[type] = None) -> bool:
+        """Full match: type (by MRO or name), then shape, then dtype — in that
+        order so the O(n) sequence dtype scan only ever runs on a value whose
+        shape already fit the pattern."""
+        if self.matches_type(real_type if real_type is not None else type(value)) < 0:
+            return False
+        if not self.matches_shape(value_shape(value)):
+            return False
+        return self.matches_dtype(value)
+
+
+# ---------------------------------------------------------------------------
+# value → (shape, dtype)
+# ---------------------------------------------------------------------------
+
+def mro_distance(of, real_type: type) -> int:
+    """Index in `real_type.__mro__` of the class `of` names (a type, or a
+    type's __name__), or -1 when no class in the MRO matches."""
+    mro = getattr(real_type, "__mro__", None)
+    if mro is None:
+        return -1
+    if isinstance(of, str):
+        for i, t in enumerate(mro):
+            if t.__name__ == of:
+                return i
+        return -1
+    for i, t in enumerate(mro):
+        if t is of:
+            return i
+    return -1
+
+
+def value_shape(value) -> Optional[tuple]:
+    """The value's shape tuple, or None when it has none.
+
+    Array-likes (anything with a tuple-able `.shape`: torch tensors, ndarrays,
+    GLTexture, CudaVolumeView …) report it directly; tuples/lists report
+    `(len,)` — a sequence is a 1-D array. str/bytes/dicts are not shaped."""
+    shape = getattr(value, "shape", None)
+    if shape is not None:
+        try:
+            return tuple(int(d) for d in shape)
+        except (TypeError, ValueError):
+            return None
+    if isinstance(value, (tuple, list)):
+        return (len(value),)
+    return None
+
+
+def _kind_of_dtype(dtype):
+    """Map a torch / numpy dtype object to a Python kind, duck-typed so this
+    module never imports either library."""
+    # numpy: dtype.kind in 'biufcmMOSUV'
+    kind_char = getattr(dtype, "kind", None)
+    if isinstance(kind_char, str):
+        return {"b": bool, "i": int, "u": int, "f": float, "c": complex}.get(kind_char)
+    # torch: is_floating_point / is_complex properties; bool by name.
+    if getattr(dtype, "is_floating_point", False):
+        return float
+    if getattr(dtype, "is_complex", False):
+        return complex
+    name = str(dtype)
+    if name.endswith("bool"):
+        return bool
+    if "int" in name:
+        return int
+    return None
+
+
+def value_dtype(value):
+    """The value's KIND (float / int / bool / complex) or None.
+
+    Array-likes map their dtype. Sequences promote like torch.result_type:
+    any float → float, else all int → int, else all bool → bool; any other
+    element kind → None. Sequences past SEQ_DTYPE_SCAN_CAP are None."""
+    dtype = getattr(value, "dtype", None)
+    if dtype is not None:
+        return _kind_of_dtype(dtype)
+    if isinstance(value, (tuple, list)):
+        if len(value) > SEQ_DTYPE_SCAN_CAP:
+            return None
+        rank = 0  # 0 empty, 1 bool, 2 int, 3 float, 4 complex - promotion order
+        for c in value:
+            # bool first: it's an int subclass. duck-type checks are the fast
+            # path; the isinstance fallbacks catch numpy scalars & subclasses.
+            t = type(c)
+            if t is bool or isinstance(c, bool):
+                r = 1
+            elif t is int or isinstance(c, int):
+                r = 2
+            elif t is float or isinstance(c, float):
+                r = 3
+            elif isinstance(c, complex):
+                r = 4
+            else:
+                # numpy / torch 0-d scalars carry a dtype of their kind.
+                k = _kind_of_dtype(getattr(c, "dtype", None))
+                if k is None:
+                    return None
+                r = {bool: 1, int: 2, float: 3, complex: 4}[k]
+            if r > rank:
+                rank = r
+        return (None, bool, int, float, complex)[rank]
+    return None
+
+
+def shape_matches(pattern: tuple, shape: tuple) -> bool:
+    """Does the concrete `shape` fit the `pattern`? See the module doc."""
+    if pattern and pattern[-1] is Ellipsis:
+        fixed = pattern[:-1]
+        if len(shape) < len(fixed):
+            return False
+    else:
+        fixed = pattern
+        if len(shape) != len(fixed):
+            return False
+    for want, got in zip(fixed, shape):
+        if want is None:
+            continue
+        if isinstance(want, frozenset):
+            if got not in want:
+                return False
+        elif got != want:
+            return False
+    return True
+
+
+# ---------------------------------------------------------------------------
+# Searching over a registry
+# ---------------------------------------------------------------------------
+
+def best_match(entries: Iterable, value, real_type: Optional[type] = None):
+    """Pick the registered function whose `Shaped` key best fits `value`.
+
+    `entries` iterates `(Shaped, func)` pairs (a dict's `.items()`). Returns
+    the func or None. Most constrained pattern (score) wins; ties go to the
+    closest MRO match, then to the earliest registered. The value's shape is
+    extracted at most once, and only when some entry's type matched."""
+    if real_type is None:
+        real_type = type(value)
+    best = None
+    best_key = None
+    shape = _UNSET = object()
+    for shaped, func in entries:
+        if func is None or not isinstance(shaped, Shaped):
+            continue
+        dist = shaped.matches_type(real_type)
+        if dist < 0:
+            continue
+        if shape is _UNSET:
+            shape = value_shape(value)
+        if shape is None or not shaped.matches_shape(shape):
+            continue
+        # (score desc, mro distance asc) - compared as a tuple, first wins on ties.
+        key = (shaped.score, -dist)
+        if best_key is None or key > best_key:
+            if not shaped.matches_dtype(value):
+                continue
+            best, best_key = func, key
+    return best

meltygui/core/rendering/window_decoration.py

@@ -0,0 +1,25 @@
+
+
+_register = None
+_pending = []
+
+
+def set_window_registrar(register_fn):
+    global _register
+    _register = register_fn
+    for cls, kwargs in _pending:
+        register_fn(cls, kwargs)
+    _pending.clear()
+
+#[tint=(0.0, 0.541, 0.85)]
+def window(cls=None, **kwargs):
+    def wrap(cls):
+        if _register is None:
+            _pending.append((cls, kwargs))
+        else:
+            _register(cls, kwargs)
+        return cls
+
+    if cls is None:
+        return wrap
+    return wrap(cls)

meltygui/core/runtime/__init__.py

@@ -0,0 +1 @@
+"""Shared framework runtime machinery."""