meltygui 0.1.0__py3-none-any.whl

meltygui/completion/providers/oauth_popup.py

@@ -0,0 +1,220 @@
+"""Placed sign-in popups — Wayland refuses window positioning, so auth pages
+open as a chromeless Chromium `--app` window forced onto XWAYLAND
+(`--ozone-platform=x11`, where placement IS allowed) and a placement thread
+parks it beside the pointer — i.e. over the button that opened it — with
+xdotool, sized for a login form.
+
+A dedicated profile (`~/.lsd/oauth-browser`) does two jobs: it guarantees a
+FRESH browser instance (flags would be swallowed by an already-running
+Wayland Chrome otherwise) and it keeps its own Google session between
+sign-ins — the first one asks for credentials, later ones are one click.
+
+`shim_env` covers the flow the studio doesn't open itself: `claude auth
+login` calls xdg-open on its own, so its PATH gets a shim dir whose
+xdg-open launches the same placed popup (`place_async` watches for it).
+
+Fallback at every step — popups disabled (Toggles.InternetAccounts.
+use_oauth_popup), no Chromium-family browser, no DISPLAY, the browser
+dying before a window appears — is plain copilot.open_url. Every spawn is
+posix_spawn-style (absolute paths, close_fds=False — never fork the
+studio's CUDA/GL address space).
+"""
+from __future__ import annotations
+
+import os
+import shutil
+import stat
+import subprocess
+import threading
+import time
+from pathlib import Path
+
+# Protocol constants (not knobs): the WM_CLASS the popup is found/closed by,
+# and where the shim + browser profile go.
+WINDOW_CLASS = "lsd-oauth"
+PROFILE_DIR = Path.home() / ".lsd" / "oauth-browser"
+SHIM_DIR = Path.home() / ".lsd" / "oauth-shim"
+
+
+def find_browser(explicit=""):
+    """A Chromium-family browser (only they have --app / --ozone-platform)."""
+    if explicit:
+        found = shutil.which(explicit) or (explicit if Path(explicit).is_file() else None)
+        return found
+    for name in ("google-chrome", "chromium", "chromium-browser"):
+        found = shutil.which(name)
+        if found:
+            return found
+    return None
+
+
+def popup_available() -> bool:
+    from meltygui.core.runtime.toggles import Toggles
+    return (bool(Toggles.InternetAccounts.use_oauth_popup)
+            and bool(os.environ.get("DISPLAY"))
+            and find_browser(Toggles.InternetAccounts.oauth_popup_browser) is not None
+            and shutil.which("xdotool") is not None)
+
+
+class PopupHandle:
+    def __init__(self, process):
+        self.process = process
+        self.placed = False
+
+    def close(self):
+        """End of the flow: the popup's job is done — close it."""
+        if self.process is not None and self.process.poll() is None:
+            try:
+                self.process.terminate()
+            except OSError:
+                pass
+
+
+def open_auth_popup(url, browser=None, xdotool=None, size=None, place_timeout_s=15.0):
+    """Open `url` as a placed popup; falls back to copilot.open_url and
+    returns None when it can't. Returns a PopupHandle (close() on flow end)
+    when the popup browser was launched."""
+    from meltygui.core.runtime.toggles import Toggles
+    browser = browser or (find_browser(Toggles.InternetAccounts.oauth_popup_browser)
+                          if Toggles.InternetAccounts.use_oauth_popup else None)
+    xdotool = xdotool or shutil.which("xdotool")
+    if not browser or not xdotool or not os.environ.get("DISPLAY"):
+        _fallback(url)
+        return None
+    width, height = size or Toggles.InternetAccounts.oauth_popup_size
+    PROFILE_DIR.mkdir(parents=True, exist_ok=True)
+    try:
+        process = subprocess.Popen(
+            [browser, f"--app={url}", "--ozone-platform=x11", f"--class={WINDOW_CLASS}",
+             f"--window-size={width},{height}", f"--user-data-dir={PROFILE_DIR}",
+             "--no-first-run", "--no-default-browser-check"],
+            close_fds=False, stdin=subprocess.DEVNULL,
+            stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+    except OSError:
+        _fallback(url)
+        return None
+    handle = PopupHandle(process)
+    threading.Thread(target=_place, args=(handle, url, xdotool, (width, height), place_timeout_s),
+                     daemon=True, name="oauth-popup-place").start()
+    return handle
+
+
+def place_async(xdotool=None, size=None, place_timeout_s=20.0):
+    """Watch for a popup some OTHER process launches (the xdg-open shim under
+    `claude auth login`) and park it like open_auth_popup does."""
+    from meltygui.core.runtime.toggles import Toggles
+    xdotool = xdotool or shutil.which("xdotool")
+    if xdotool is None:
+        return
+    handle = PopupHandle(None)
+    threading.Thread(target=_place,
+                     args=(handle, None, xdotool, size or Toggles.InternetAccounts.oauth_popup_size,
+                           place_timeout_s),
+                     daemon=True, name="oauth-popup-place").start()
+
+
+def close_popups(xdotool=None):
+    """Close every lsd-oauth window (flows we don't hold a Popen for)."""
+    xdotool = xdotool or shutil.which("xdotool")
+    if xdotool is None:
+        return
+    try:
+        found = subprocess.run([xdotool, "search", "--class", WINDOW_CLASS],
+                               capture_output=True, text=True, timeout=5, close_fds=False)
+        for window_id in found.stdout.split():
+            subprocess.run([xdotool, "windowclose", window_id],
+                           timeout=5, close_fds=False,
+                           stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+    except (OSError, subprocess.TimeoutExpired):
+        pass
+
+
+# ── the xdg-open shim for `claude auth login` ─────────────────────────────
+
+def write_shim(browser=None):
+    """`~/.lsd/oauth-shim/xdg-open`: launches the placed popup for whatever
+    URL Claude Code opens. Regenerated per use so browser/size changes land."""
+    from meltygui.core.runtime.toggles import Toggles
+    browser = browser or find_browser(Toggles.InternetAccounts.oauth_popup_browser)
+    if browser is None:
+        return None
+    width, height = Toggles.InternetAccounts.oauth_popup_size
+    PROFILE_DIR.mkdir(parents=True, exist_ok=True)
+    SHIM_DIR.mkdir(parents=True, exist_ok=True)
+    shim = SHIM_DIR / "xdg-open"
+    shim.write_text(
+        "#!/bin/sh\n"
+        "# latent-descent oauth shim: Claude Code's browser-open, as a placed popup\n"
+        f'exec "{browser}" "--app=$1" --ozone-platform=x11 --class={WINDOW_CLASS} '
+        f"--window-size={width},{height} \"--user-data-dir={PROFILE_DIR}\" "
+        "--no-first-run --no-default-browser-check "
+        ">/dev/null 2>&1 &\n")
+    shim.chmod(shim.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+    return shim
+
+
+def shim_env(base_env):
+    """`base_env` with the shim first on PATH (and as $BROWSER) — pass to the
+    `claude auth login` subprocess; unchanged when popups can't happen."""
+    if not popup_available() or write_shim() is None:
+        return dict(base_env)
+    env = dict(base_env)
+    env["PATH"] = f"{SHIM_DIR}:{env.get('PATH', '')}"
+    env["BROWSER"] = str(SHIM_DIR / "xdg-open")
+    return env
+
+
+# ── placement ─────────────────────────────────────────────────────────────
+
+def _place(handle, url, xdotool, size, timeout_s):
+    """Wait for the popup's X window, then park it beside the pointer
+    (clamped to the display span) and raise it. If the browser died before
+    a window appeared (bad flags, broken profile) fall back to xdg-open."""
+    width, height = size
+    # Within this margin of any display edge the popup is pushed inward.
+    margin = 16
+    # The popup is this far above the pointer so the title area isn't under it.
+    pointer_lift = 60
+    deadline = time.monotonic() + timeout_s
+
+    def run(*args):
+        return subprocess.run([xdotool, *args], capture_output=True, text=True,
+                              timeout=10, close_fds=False)
+
+    window_id = None
+    while time.monotonic() < deadline and window_id is None:
+        try:
+            found = run("search", "--onlyvisible", "--class", WINDOW_CLASS)
+            ids = found.stdout.split()
+            if ids:
+                window_id = ids[-1]
+                break
+        except (OSError, subprocess.TimeoutExpired):
+            return
+        if (handle.process is not None and handle.process.poll() not in (None, 0)
+                and url is not None):
+            _fallback(url)          # the popup was but not showing anything
+            return
+        time.sleep(0.25)
+    if window_id is None:
+        return
+    try:
+        mouse = run("getmouselocation", "--shell").stdout
+        position = dict(line.split("=", 1) for line in mouse.split() if "=" in line)
+        screen = run("getdisplaygeometry").stdout.split()
+        screen_width, screen_height = int(screen[0]), int(screen[1])
+        x = max(margin, min(int(position.get("X", 0)) - width // 2, screen_width - width - margin))
+        y = max(margin, min(int(position.get("Y", 0)) - pointer_lift, screen_height - height - margin))
+        run("windowmove", window_id, str(x), str(y))
+        run("windowactivate", window_id)
+        handle.placed = True
+    except (OSError, subprocess.TimeoutExpired, ValueError, IndexError):
+        pass
+
+
+def _fallback(url):
+    try:
+        from meltygui.completion.providers.copilot import open_url
+        open_url(url)
+    except Exception:
+        pass

meltygui/completion/providers/ollama.py

@@ -0,0 +1,320 @@
+"""Ollama FIM provider — native fill-in-the-middle through a local Ollama
+server (`/api/generate` with `suffix`, streamed). Any FIM-trained model
+works (`qwen2.5-coder:*`, `codellama:*-code`, `deepseek-coder*`,
+`starcoder2`); a chat-only model ignores `suffix` and completes the prefix.
+
+Session: one keep-alive HTTP client per host (an Internet Accounts entry of
+kind "ollama"). The account also carries the DEVICE the model should live
+on (`device`: "auto" | "cpu" | "gpu:N" in Ollama's own GPU numbering) —
+every request passes it as llama.cpp options (`main_gpu` / `num_gpu: 0`),
+which is how Ollama decides placement (verified 2026-08-22: main_gpu=2 put
+the model on the H100). Ollama numbers GPUs in CUDA-runtime order —
+`gpu_inventory()` reads that order (names + live memory) from `torch.cuda`,
+which shares the process's already-initialized CUDA runtime and is thread-
+safe, so the probe never spins up a second CUDA context (a bare
+`pycuda.driver.init()` on a probe thread could race the render thread's GL
+context at boot and hang the load) and never shells out to nvidia-smi.
+"""
+from __future__ import annotations
+
+import json
+import threading
+import time
+
+from meltygui.completion.fim import FimRequest
+from meltygui.completion.fim import FimResult
+from meltygui.completion.fim import FimSession
+from meltygui.completion.fim import fim_provider
+
+
+class OllamaSession(FimSession):
+    """One keep-alive client for the Ollama host of Internet Accounts entry
+    `account` (kind "ollama": `host`); an explicit `host` overrides it."""
+    KIND = "ollama"
+
+    def __init__(self, account="default", host=None, timeout_s=30.0):
+        import httpx
+        from meltygui.accounts.internet_accounts import account_field
+        self.account = account
+        host = host or account_field("ollama", account, "host") or "http://localhost:11434"
+        self.host = host.rstrip("/")
+        # Short CONNECT timeout so a down/unreachable server fails fast instead
+        # of blocking a gui thread for the long read timeout; generation
+        # itself keeps the long read timeout.
+        self.client = httpx.Client(base_url=self.host,
+                                   timeout=httpx.Timeout(timeout_s, connect=2.0))
+        self._status = ("ready",)
+
+    def status(self):
+        return self._status
+
+    def close(self):
+        try:
+            self.client.close()
+        except Exception:
+            pass
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# Helpers
+# ──────────────────────────────────────────────────────────────────────────
+
+def device_options(device) -> dict:
+    """llama.cpp options for an account's `device` setting."""
+    if not device or device == "auto":
+        return {}
+    if device == "cpu":
+        return {"num_gpu": 0}
+    if device.startswith("gpu:"):
+        try:
+            return {"main_gpu": int(device[4:])}
+        except ValueError:
+            return {}
+    return {}
+
+
+_inventory_cache = [0.0, None]
+
+
+def gpu_inventory(max_age=3.0) -> list:
+    """[{ollama_index, name, short, used_mib, total_mib}] in OLLAMA (CUDA
+    runtime) order — read from torch.cuda, which shares the process's
+    already-initialized CUDA runtime (same device order Ollama's llama.cpp
+    sees) and is thread-safe. Deliberately NOT pycuda: a bare
+    `pycuda.driver.init()` on a probe thread can race the render thread's
+    CUDA/GL context creation at boot and hang the load. No subprocess
+    either — no nvidia-smi. Best-effort; cached briefly."""
+    now = time.monotonic()
+    if _inventory_cache[1] is not None and now - _inventory_cache[0] < max_age:
+        return _inventory_cache[1]
+    gpus = []
+    try:
+        import torch
+        if torch.cuda.is_available():
+            for i in range(torch.cuda.device_count()):
+                p = torch.cuda.get_device_properties(i)
+                try:
+                    free, total = torch.cuda.mem_get_info(i)
+                except Exception:
+                    free, total = 0, int(getattr(p, "total_memory", 0))
+                name = p.name.replace("NVIDIA ", "").replace("GeForce ", "")
+                gpus.append({"ollama_index": i, "name": name,
+                             "short": name.replace(" NVL", "").replace("RTX ", ""),
+                             "used_mib": int((total - free) / 1048576),
+                             "total_mib": int(total / 1048576), "order": "cuda"})
+    except Exception:
+        gpus = []
+    _inventory_cache[0] = now
+    _inventory_cache[1] = gpus
+    return gpus
+
+
+def _gpu_for_vram(gpus, size_vram) -> dict | None:
+    """The GPU a model of `size_vram` bytes most likely sits on — the one
+    whose used memory best matches (torch mem_get_info, no per-process
+    attribution needed). Good enough for one resident model."""
+    want = size_vram / 1048576
+    best, best_d = None, None
+    for g in gpus:
+        if g["used_mib"] >= 0.4 * want:
+            d = abs(g["used_mib"] - want)
+            if best_d is None or d < best_d:
+                best, best_d = g, d
+    return best
+
+
+def device_label(device, gpus=None) -> str:
+    """Label for a device setting. `gpus` is the CACHED inventory (or None) —
+    this NEVER queries hardware, so it is safe on the render thread. Without
+    an inventory a GPU shows as a bare "GPUn" until a probe fills the names."""
+    if not device or device == "auto":
+        return "auto"
+    if device == "cpu":
+        return "CPU"
+    if device.startswith("gpu:"):
+        try:
+            i = int(device[4:])
+        except ValueError:
+            return device
+        for g in (gpus or ()):
+            if g["ollama_index"] == i:
+                return f"GPU{i} {g['short']}"
+        return f"GPU{i}"
+    return device
+
+
+def device_choices(gpus=None) -> list:
+    """Device options from the CACHED inventory (or None) — no hardware
+    query. Falls back to auto/cpu only until a probe supplies the GPUs."""
+    return ["auto"] + [f"gpu:{g['ollama_index']}" for g in (gpus or ())] + ["cpu"]
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# Model management (used by the Internet Accounts window)
+# ──────────────────────────────────────────────────────────────────────────
+
+def list_models(client) -> list:
+    """[{name, size, loaded, size_vram, expires_at, where}] — /api/tags
+    joined with /api/ps and the runners' GPU placement."""
+    tags = client.get("/api/tags", timeout=5.0).json().get("models") or []
+    try:
+        running = {m["name"]: m for m in (client.get("/api/ps", timeout=5.0).json().get("models") or [])}
+    except Exception:
+        running = {}
+    gpus = gpu_inventory() if running else []
+    out = []
+    for t in tags:
+        name = t.get("name", "?")
+        r = running.get(name)
+        loaded = r is not None
+        vram = int(r.get("size_vram") or 0) if r else 0
+        w = None
+        if loaded:
+            if vram == 0:
+                w = "CPU"
+            else:
+                g = _gpu_for_vram(gpus, vram)
+                w = f"GPU{g['ollama_index']} {g['short']}" if g else "GPU"
+        out.append({"name": name, "size": int(t.get("size") or 0), "loaded": loaded,
+                    "size_vram": vram, "expires_at": (r or {}).get("expires_at"), "where": w,
+                    "family": ((t.get("details") or {}).get("family") or "")})
+    out.sort(key=lambda m: (not m["loaded"], m["name"]))
+    return out
+
+
+def load_model(client, model, device="auto", keep_alive="30m"):
+    """Load `model` onto `device` (an empty generate with keep_alive) — also
+    how a loaded model is MOVED: Ollama reloads when the options change."""
+    payload = {"model": model, "keep_alive": keep_alive, "options": device_options(device)}
+    r = client.post("/api/generate", json=payload, timeout=600.0)
+    if r.status_code != 200:
+        raise RuntimeError(f"ollama {r.status_code}: {r.text[:200]}")
+
+
+def unload_model(client, model):
+    r = client.post("/api/generate", json={"model": model, "keep_alive": 0}, timeout=60.0)
+    if r.status_code != 200:
+        raise RuntimeError(f"ollama {r.status_code}: {r.text[:200]}")
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# Provider
+# ──────────────────────────────────────────────────────────────────────────
+
+def _window(req: FimRequest, prefix_chars: int, suffix_chars: int):
+    prefix = req.annotated_prefix()
+    if len(prefix) > prefix_chars:
+        cut = prefix.rfind("\n", 0, len(prefix) - prefix_chars)
+        prefix = prefix[cut + 1:] if cut >= 0 else prefix[-prefix_chars:]
+    suffix = req.suffix
+    if len(suffix) > suffix_chars:
+        cut = suffix.find("\n", suffix_chars)
+        suffix = suffix[:cut] if cut >= 0 else suffix[:suffix_chars]
+    return prefix, suffix
+
+
+@fim_provider(name="ollama", session=OllamaSession)
+def ollama_fim(req: FimRequest, session: OllamaSession, model="qwen2.5-coder:7b",
+               prefix_chars=6000, suffix_chars=1500, context_chars=3000,
+               temperature=0.2, device=None, keep_alive=None) -> FimResult:
+    """Local FIM. Stable context rides ahead of the prefix as commented
+    blocks (FIM models have no side channel for it); the run block is
+    inlined through `annotated_prefix`. `device` / `keep_alive` default to
+    the account's settings (Internet Accounts → Ollama)."""
+    from meltygui.core.runtime.toggles import Toggles
+    from meltygui.accounts.internet_accounts import account_field
+    if device is None:
+        device = account_field("ollama", session.account, "device", "auto")
+    if keep_alive is None:
+        keep_alive = Toggles.Fim.ollama_keep_alive
+    prefix, suffix = _window(req, prefix_chars, suffix_chars)
+    ctx_text = req.context.render(("stable",)) if req.context is not None else ""
+    if ctx_text:
+        ctx_text = ctx_text[-context_chars:]
+        commented = "\n".join("# " + ln if ln.strip() else "#" for ln in ctx_text.split("\n"))
+        prefix = "# --- context ---\n" + commented + "\n# --- end context ---\n\n" + prefix
+    options = {"num_predict": max(16, req.max_tokens), "temperature": temperature}
+    options.update(device_options(device))
+    payload = {"model": model, "prompt": prefix, "suffix": suffix, "stream": True,
+               "keep_alive": keep_alive, "options": options}
+    acc = []
+    try:
+        try:
+            reason = _generate(session, payload, req, acc)
+        except _Unsupported as e:
+            # Not a FIM model - retry prefix-only (and with thinking off for a
+            # reasoning model, whose output would otherwise all be thinking).
+            # Quality is lower - the model can't see the suffix - but the
+            # provider still works; the status says so.
+            if "insert" in e.what:
+                payload.pop("suffix", None)
+            reason = None
+            if "insert" in e.what or "think" in e.what:
+                payload["think"] = False
+                try:
+                    reason = _generate(session, payload, req, acc)
+                except _Unsupported as e2:
+                    if "think" not in e2.what:
+                        raise
+                    payload.pop("think", None)
+                    reason = _generate(session, payload, req, acc)
+            session._status = ("ready", f"{model}: no FIM support, prefix-only")
+            return FimResult("".join(acc), provider="ollama", truncated=(reason == "length"))
+    except Exception as e:
+        session._status = ("error", str(e))
+        raise
+    session._status = ("ready",)
+    # done_reason "length" = hit num_predict (more to come → continue on Tab);
+    # "stop" = the model emitted an end token (done, don't auto-continue).
+    return FimResult("".join(acc), provider="ollama", truncated=(reason == "length"))
+
+
+class _Unsupported(RuntimeError):
+    def __init__(self, what):
+        super().__init__(f"ollama: {what}")
+        self.what = what
+
+
+def _generate(session, payload, req, acc):
+    """Stream one /api/generate call into `acc` (list of pieces), emitting
+    the running text. Returns the final `done_reason` ("stop" | "length" |
+    None). Raises _Unsupported for the model-capability errors ("does not
+    support insert/thinking") so the caller can adapt."""
+    acc.clear()
+    saw_thinking = False
+    done_reason = None
+    with session.client.stream("POST", "/api/generate", json=payload) as resp:
+        if resp.status_code != 200:
+            body = resp.read().decode("utf-8", "replace")[:300]
+            if "does not support" in body:
+                raise _Unsupported(body)
+            raise RuntimeError(f"ollama {resp.status_code}: {body}")
+        for line in resp.iter_lines():
+            if req.cancelled.is_set():
+                break
+            if not line:
+                continue
+            try:
+                msg = json.loads(line)
+            except ValueError:
+                continue
+            if msg.get("error"):
+                err = str(msg["error"])
+                if "does not support" in err:
+                    raise _Unsupported(err)
+                raise RuntimeError(f"ollama: {err}")
+            if msg.get("thinking"):
+                saw_thinking = True
+            piece = msg.get("response", "")
+            if piece:
+                acc.append(piece)
+                req.emit("".join(acc))
+            if msg.get("done"):
+                done_reason = msg.get("done_reason")
+                break
+    if saw_thinking and not acc and "think" not in payload and not req.cancelled.is_set():
+        # A reasoning model spent the entire budget thinking (happens when the
+        # suffix is empty, so Ollama didn't reject the insert) - retry with
+        # thinking off so the tokens go to the completion.
+        raise _Unsupported("thinking consumed the budget")
+    return done_reason

meltygui/completion/providers/profiles.py

@@ -0,0 +1,23 @@
+"""Named FIM profiles: a provider plus configuration. Every provider already
+registers a default profile under its own name ("claude", "ollama"); add
+variants here. Kwargs that name a parameter of the provider's session
+class select/construct the SESSION (so two profiles with different session
+kwargs get two live sessions — e.g. two accounts); the rest override the
+provider function's per-request params.
+
+    fim_profile("claude-fast", claude_fim, model="claude-haiku-4-5")
+    fim_profile("copilot-work", copilot_fim, config_dir="~/.config/github-copilot-work")
+
+Pick a profile per editor with `draw_text(..., fim="claude-fast")` or
+globally with `Toggles.Fim.profile`.
+"""
+from meltygui.completion.fim import fim_profile
+from meltygui.completion.providers.claude import claude_fim
+from meltygui.completion.providers.copilot import copilot_fim
+from meltygui.completion.providers.ollama import ollama_fim
+
+fim_profile("claude-fast", claude_fim, model="claude-haiku-4-5", effort=None)
+fim_profile("ollama-qwen", ollama_fim, model="qwen2.5-coder:7b")
+# A second github login: add a "copilot" account in Internet Accounts with
+# its own config dir, then point a profile at it by account id.
+fim_profile("copilot-2", copilot_fim, account="copilot-2")

meltygui/core/README.md

@@ -0,0 +1,88 @@
+# Core: rendering plumbing and shared runtime
+
+Core makes reusable render functions work: it supplies their inputs, tracks state,
+runs converters, dispatches events, caches drawing and connects windows to the OS.
+`Melty` owns the shared runtime. Feature rendering belongs in `view/<feature>_view.py`;
+feature adapters belong in `model/<feature>_model.py`; injected feature state belongs
+in `state/<feature>_state.py`.
+
+## Where to start
+
+The root keeps five Python modules: `core_render.py`, `melty.py`,
+`definition_hotswap.py`, `module_names.py`, and the package initializer.
+`module_map.json` translates identifiers in older saved sessions.
+Everything else is grouped by the runtime responsibility it serves:
+
+| Folder | Responsibility and main entry points |
+|---|---|
+| `input/` | Event delivery, devices, hit testing, drag/drop and selection: `input_handler.py`, `collision.py`, `drag_drop_core.py` |
+| `rendering/` | Render dispatch, registration, parameter injection support, modes and decorators: `render_dispatch.py`, `parameter_core.py`, `mode.py` |
+| `conversion/` | Dict-like objects, conversion graphs, hosting and persistence: `dict_conversion.py`, `render_host.py`, `load_save_v2.py` |
+| `cache/` | Drawing caches and invalidation: `tile_cache.py`, `invalidation_tracker.py` |
+| `windowing/` | Surface lifecycle, native windows, chrome and platform backends: `surface.py`, `window_api.py`, `backends/` |
+| `graphics/` | Shared GL resources, shaders, overlays, capture and tensor/graph integration: `gl_state.py`, `shader_func.py`, `lut_core.py`, `cuda_context_core.py`, `cuda_interop_core.py`, `cuda_kernel_core.py` |
+| `layout/` | Cursor, grid, column, header and dropdown plumbing |
+| `styling/` | Shared styles, colours, fonts and font warmup |
+| `files/` | Filesystem polling, metadata and file/import-tree integration |
+| `runtime/` | App/session lifecycle, scheduling, settings and shared process helpers |
+| `diagnostics/` | Notifications, profiling, tracing, inspection and diagnostics integration |
+| `automation/` | Orchestration, actions, queries, search and MCP integration |
+| `services/` | Terminal, chat and account runtime integration |
+
+These folders organize wiring; they do not turn feature algorithms or local
+presentation into core code. Some inherited integration modules remain mixed;
+see [the outstanding ownership review](../../docs/ARCHITECTURE_DEBT.md).
+
+## Shared presentation inputs
+
+Render functions can declare `ui_scale` and `font_manager` in their signatures,
+alongside the existing `style_manager` input. Core supplies the current runtime
+scale and font manager; explicit scale/font-manager overrides are supported for
+previews. These dependencies are excluded from saved view parameters and the
+parameter controls. Views can use their own `draw_state.depth_and_layer` for
+local drawing depth. This keeps feature presentation independent of `Melty`
+lookups without making callers pass the same plumbing repeatedly.
+
+`keyboard_available` is true when no text editor owns keyboard focus;
+`pointer_buttons_down` reports whether any primary pointer button is held.
+Core supplies these only to views declaring them. Like scale and font context,
+they allow explicit overrides and are excluded from saved parameter controls.
+
+Palette consumers declare `luts`. Core injects the shared `LutPalette` from
+`Melty.luts`, or accepts an explicit override, and subscribes cached consumers
+before the render-cache gate. `luts.texture(name)` is an integer-like texture ID:
+the model handles lazy uploads, updates and per-context storage. There is no
+palette host or separate resource service. `GLState` releases context resources
+when a surface closes. Palette values and proxies belong in `model/lut_model.py`;
+selection and swatches belong in `view/lut_view.py`.
+
+## CUDA interop ownership
+
+`cuda_context_core.py` owns primary-context leases and scoped device activation
+for voxel kernels, line kernels and GL interop. Runtime state lives on
+`Melty.cuda_interop`; the existing field also holds the per-device context pool.
+`cuda_interop_core.py` selects the GL-compatible device and manages registered
+buffers, mapping and copies through that shared context manager.
+`model/cuda_texture_model.py` owns versioned tensor uploads as `GLTexture` values.
+Their composite allocations use the caller's `GLState`, including partial-allocation
+cleanup and deferred unregistration retries. Feature renderers do not own CUDA
+context setup. `cuda_kernel_core.py` owns compilation and cached modules. Voxel and line CUDA
+presentation live in `view/voxel_cuda_view.py` and `view/graph_cuda_view.py`.
+
+## Why mode has three files
+
+`rendering/mode.py` defines the real enum and its renderer/converter policies. `rendering/modes.py`
+provides lazy `Modes.X` handles so decorators can refer to modes before their
+renderers finish importing. `rendering/mode_defaults.py` holds shared type-to-mode defaults,
+including delayed registration for optional dependencies. Combining these at
+import time would recreate the mode/renderer import cycle.
+
+The public package exports remain available from `meltygui`. Internal imports
+use current modules; there are no legacy import aliases, forwarding shims or
+virtual historical namespaces. Definition hotswap preserves live objects and
+state. Saved-name translation belongs to session loading, and source navigation
+resolves actual imports. Update the editor and its Pro dependency with source moves.
+
+See [the move inventory and checks](../../docs/CORE_RELOCATION.md). The mixed
+`state/new_core_model.py` and the text-editor implementation await the separate
+editor/state refactor.

meltygui/core/__init__.py

@@ -0,0 +1 @@
+"""Shared framework wiring."""

meltygui/core/automation/__init__.py

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