meltygui 0.1.0__tar.gz → 0.1.3__tar.gz

{meltygui-0.1.0 → meltygui-0.1.3}/.gitignore

@@ -6,5 +6,5 @@ dist/
 build/
 *.egg-info/
 .melty/
-
+.DS_Store
 .idea/

{meltygui-0.1.0 → meltygui-0.1.3}/PKG-INFO

@@ -1,10 +1,11 @@
 Metadata-Version: 2.5
 Name: meltygui
-Version: 0.1.0
+Version: 0.1.3
 Summary: Immediate-mode Python UI, live inspection, HDR and tensor visualization
 License-Expression: Apache-2.0
 License-File: LICENSE
 Classifier: Development Status :: 3 - Alpha
+Classifier: Operating System :: MacOS :: MacOS X
 Classifier: Operating System :: Microsoft :: Windows
 Classifier: Operating System :: POSIX :: Linux
 Classifier: Programming Language :: Python :: 3.11
@@ -17,8 +18,8 @@ Requires-Dist: glfw>=2.10
 Requires-Dist: httpx>=0.27
 Requires-Dist: jedi>=0.19
 Requires-Dist: libcst>=1.4
-Requires-Dist: mcp>=1.0
-Requires-Dist: meltygui-imgui[glfw]<2.0.1,>=2.0.0.post1
+Requires-Dist: mcp>=2.0
+Requires-Dist: meltygui-imgui[glfw]<2.0.2,>=2.0.1
 Requires-Dist: numpy>=1.26
 Requires-Dist: packaging>=24
 Requires-Dist: pillow>=10
@@ -33,13 +34,15 @@ Requires-Dist: symspellpy>=6.7
 Requires-Dist: tomlkit>=0.13
 Requires-Dist: uvicorn>=0.30
 Requires-Dist: watchdog>=4
+Provides-Extra: claude
+Requires-Dist: claude-agent-sdk>=0.2.152; extra == 'claude'
 Provides-Extra: input
 Requires-Dist: evdev>=1.7; (sys_platform == 'linux') and extra == 'input'
 Requires-Dist: pynput>=1.7; extra == 'input'
 Provides-Extra: profile
 Requires-Dist: line-profiler>=4; extra == 'profile'
 Provides-Extra: tensor
-Requires-Dist: meltygui-pycuda<2026.2,>=2026.1.post1; (sys_platform == 'linux') and extra == 'tensor'
+Requires-Dist: meltygui-pycuda<2026.3,>=2026.2; (sys_platform == 'linux') and extra == 'tensor'
 Requires-Dist: torch>=2.2; extra == 'tensor'
 Description-Content-Type: text/markdown
 
@@ -58,11 +61,13 @@ MeltyGUI is capable of rendering tensors exceeding 64GB in size. The primary cha
 MeltyGUI is not yet published to PyPI. For now, install from a checkout using
 [the setup guide](docs/DEVELOPMENT.md#setup).
 
-The current setup targets Linux x86-64 with Python 3.11, 3.12 or 3.13 and a
-working OpenGL 4.3 context. CUDA tensor rendering also requires PyTorch, an
+Linux x86-64 uses Python 3.11, 3.12 or 3.13 and OpenGL 4.3. The UI and editor
+also run on Apple Silicon macOS with Python 3.12, OpenGL 4.1 and Retina
+rendering. CUDA tensor rendering requires PyTorch, an
 NVIDIA GPU, a CUDA toolkit, and MeltyGUI's GL-enabled CUDA binding. The native
 bindings install as prebuilt wheels on those targets; elsewhere installers
 compile them, see [when no wheel matches](docs/SUPPORT_WHEELS.md#when-no-wheel-matches).
+CUDA rendering is unavailable on macOS.
 
 ## Visualize a tensor
 

{meltygui-0.1.0 → meltygui-0.1.3}/README.md

@@ -13,11 +13,13 @@ MeltyGUI is capable of rendering tensors exceeding 64GB in size. The primary cha
 MeltyGUI is not yet published to PyPI. For now, install from a checkout using
 [the setup guide](docs/DEVELOPMENT.md#setup).
 
-The current setup targets Linux x86-64 with Python 3.11, 3.12 or 3.13 and a
-working OpenGL 4.3 context. CUDA tensor rendering also requires PyTorch, an
+Linux x86-64 uses Python 3.11, 3.12 or 3.13 and OpenGL 4.3. The UI and editor
+also run on Apple Silicon macOS with Python 3.12, OpenGL 4.1 and Retina
+rendering. CUDA tensor rendering requires PyTorch, an
 NVIDIA GPU, a CUDA toolkit, and MeltyGUI's GL-enabled CUDA binding. The native
 bindings install as prebuilt wheels on those targets; elsewhere installers
 compile them, see [when no wheel matches](docs/SUPPORT_WHEELS.md#when-no-wheel-matches).
+CUDA rendering is unavailable on macOS.
 
 ## Visualize a tensor
 

meltygui-0.1.3/docs/APPS.md

@@ -0,0 +1,340 @@
+# Building an app
+
+Install the framework into the same environment that runs the app. Both the
+package name and import name are `meltygui`. There is no `src` package and no
+requirement to launch from the framework checkout.
+
+When contributing reusable features to the library, also follow the
+[ownership and render-function contracts](../CONTRIBUTING.md).
+
+```python
+import meltygui
+from meltygui.core.core_render import render_func
+from meltygui.core.conversion.dict_conversion import DictConversion
+
+class EditorState(DictConversion):
+    def __init__(self):
+        super().__init__()
+        self.text = "Hello"
+
+@meltygui.glfw_window(name="Editor", app_id="my-editor", width=900, height=700)
+@render_func(use_cache=False)
+def editor(input_value=None, state: EditorState = None):
+    changed, state.text = meltygui.draw_text(state.text)
+    return changed, input_value
+```
+
+The loop starts after the main module finishes defining its windows.
+Injected state persists across frames and sessions. Call render functions every
+frame, returning `(changed, value)`. For nested windows, pass `closable=True` and
+an `open_requested` event to the same call every frame. Use `glfw_window=True` to
+host a child in a native window; its lifecycle follows the same rules.
+
+Closed, event-opened dialogs may skip the renderer call entirely. Inject a
+`WindowCallState` from `meltygui.core.windowing.window_visibility`, guard with
+`dialog.needs_call(open_requested)`, and call `dialog.draw(draw_renderer, value,
+open_requested=open_requested, ...)` inside the guard. The state keeps active
+windows receiving lifecycle calls and consumes deferred results even when a
+selection closes the window. Put default-value lookups inside the guard too.
+The guard's handles are runtime-only; the renderer still owns its saved state.
+
+### Window size and position: `initial=`, never `width=` / `height=`
+
+`width=`, `height=` and `window_pos=` on a call are applied **every frame**: they
+pin the window, so the user cannot resize or move it and the persisted geometry
+is thrown away. To give a window a starting size or place, pass
+`initial={...}`; it is written once, on the window's first frame, and the user's
+(persisted) geometry wins afterwards:
+
+```python
+draw_dep_manager(value, name="Dependencies", closable=True, as_window=True,
+                 open_requested=clicked,
+                 initial={"width": 760, "height": 620, "window_pos": (240, 90)})
+```
+
+`initial` also works at decorator level (`window(initial={...})`); a caller's
+`initial` wins over the decorator's. Pass `width=` / `height=` only to views laid
+out by their parent (a tile, a cell, a button), where the parent owns the size.
+
+## Live backgrounds and overlays on cached views
+
+Use `@render_func(draw_background=paint_backing)` for a lightweight live pass
+beneath a view's body. It receives the same arguments as `draw_overlay`, but
+its `draw_list` is the window's body list, before cached pixels and shadows.
+It runs on normal draws, cache hits, and frozen resize replay. A cached
+ancestor first places its children, then repaints their backgrounds and
+resident body pixels in parent-first order. `draw_background` replaces the
+wrapper's usual `show_bg` painting; callbacks normally return `None`, or may
+return `(False, bg_color)` to supply the background-color stack for children.
+
+`draw_text` uses the reusable `paint_view_background` callback, which honors
+`show_bg`, the view's tint/style and live bounds. Background drawing does not
+rerun the text layout. The current pixel cache still captures composited
+background and body pixels: this pass fills live bounds, including newly
+exposed space, but cannot recolor underneath an existing snapshot. Style edits
+use normal invalidation, and edits to a background callback invalidate its
+associated tiles. Use the foreground hook for uncaptured animated decoration.
+A descendant needs its own cached body for this independent replay; an
+uncached child flattened into a cached ancestor keeps that ancestor's pixels
+until the ancestor draws again, so its background cannot erase its text.
+
+Pass a plain callable as `@render_func(draw_overlay=draw_status)` or as a
+per-call `draw_overlay=` override. It runs after the body on each rendered
+frame, including blit hits, layout-owned child texture replay during frozen
+resize, and cached ancestors. Uncached
+views support the same callback. Normal idle-window sleeping still applies.
+
+Framework scrollbars use this same path for every view, with or without
+caching or freeze resize. They are never baked into tile textures. Cached
+ancestors retain descendant scrollbar owners alongside custom overlays, so
+live clipping, thumb geometry and drag subscriptions continue during replay.
+Scrollbar drag input still uses the normal event router; wheel input remains
+in the wrapper. Scroll changes invalidate content through `scroll_offset`.
+
+The callback may accept any subset of the keyword arguments `input_value`,
+`draw_state`, and `draw_list`. `input_value` is the current input supplied to
+the view; `draw_state` is its existing state. Draw primitives into the supplied
+`draw_list`, which is clipped and masked behind higher windows. Use
+`draw_state.abs_left` / `abs_top` for cached live screen coordinates. Balance
+any draw-list pushes/pops inside the callback. Use `draw_state.on_action` for
+interactions, as with the built-in scrollbar. Keep ordinary controls and
+`render_func` calls in the body; the overlay itself must not be decorated.
+
+When a cached parent owns child layout, use `draw_overlay_background=` to
+place those children with `place_overlay_view` and, when needed, paint their
+resident body pixels with `paint_cached_view`. On replay, background callbacks
+run parent first, before descendant overlays. Foreground `draw_overlay`
+callbacks then run child first, leaving the parent's controls on top. Both
+callbacks accept the same arguments and obey the same budget. Keep expensive
+resource preparation in the body. Private injected state parameters (names
+beginning with `_`) stay local to their view and are excluded from tile links.
+
+Lightweight rows can reuse the view-selection appearance with
+`Melty.paint_selection(draw_state, draw_list, (x, y, width, height))` in their
+overlay. Pass live absolute bounds; the painter uses the owning view's tint
+and clip. This avoids a render wrapper per row and keeps selection out of the
+cached body. File listings and project trees share their row-overlay painter.
+
+Callbacks must be very lightweight: taking **more than 0.5 ms of render-thread
+CPU time** disables that callback for the view. The budget uses `time.thread_time()`
+so scheduler pauses and work on other threads cannot permanently disable a cheap
+overlay. This excludes waits and is not a wall-clock latency guarantee; blocking
+I/O and resource preparation still belong outside overlays. Exceptions and invalid
+callbacks also draw an error instead. The first slow call must finish before it
+can be measured; its geometry is discarded, and subsequent frames skip it.
+Replacing the callback or hot-swapping its code retries it. Failure state is
+independent per view.
+
+See [the runnable overlay example](../examples/render_overlay.py).
+
+## Common imports
+
+```python
+from meltygui import draw_text, draw_voxels, glfw_window, imgui
+from meltygui.core.core_render import render_func
+from meltygui.core.rendering.core_decoration import defaults, no_save
+from meltygui.core.conversion.dict_conversion import DictConversion
+from meltygui.core.conversion.render_host import RenderHost
+from meltygui.view.code_view import draw_function_live
+from meltygui.graphics import Filter
+from meltygui.chat import draw_chat_interface, register_chat_backend
+```
+
+`meltygui.persisted(name, factory, app_id=...)` retains app-owned objects in
+addition to automatically retained view state. Keep an existing app's `app_id`
+when migrating so its session file remains the same.
+
+## Settings
+
+`@glfw_window(settings=...)` takes a plain dict of defaults and keeps it between
+runs. The dict is loaded in place before the loop starts, so the app reads it
+like any dict; nested dicts are sub-folders of the settings window.
+
+```python
+SETTINGS = {'font_size': 14, 'editor': {'tab_width': 4, 'wrap': False}}
+
+@meltygui.glfw_window(name="Editor", app_id="my-editor", settings=SETTINGS)
+def editor():
+    size = SETTINGS['font_size']
+```
+
+The dict's own values are the schema: a saved value only lands on a key the
+dict has, with the same type, so a renamed or removed setting disappears and a
+new one shows its default. The file is `$XDG_CONFIG_HOME/<app_id>/settings.json`
+(default `~/.config`), one section per window name, written when the settings
+window changes a value and on exit. A window with settings shows a cog in its
+title bar, just inside the window controls, that opens the settings window
+(the dict drawn as a child native window). See `meltygui/examples/settings_demo.py`.
+
+## Tiled editors
+
+Mark an editor with `@render_func(multi_instance=True)` to offer it in every
+tile's editor dropdown. Registration happens when its module is imported; the
+flag does not open a window. A render function defined elsewhere (a library
+view) registers with `multi_instance(view)`, and keeps its own `display_name` /
+`icon` / `tint` in the picker. A plain callable (no render boundary of its own)
+is offered through the host's `multi_instance_renderers`:
+
+```python
+from meltygui import draw_claude_chat     # one call of draw_chat_interface
+draw_tiles(tiles, draw_state, multi_instance_renderers=(draw_claude_chat,))
+```
+ A tile calls its editor with `layout_frame` (its
+four edge dicts); an editor that lays out columns forwards it to the view that
+does, as `draw_chat_interface(layout_frame=...)` does, so the columns stay
+inside the tile instead of adopting the window frame. A `Tile` in the app model owns the selected function
+reference and its `input_value`. `Tile` and `Split` are `DictConversion` models,
+so the normal app/session persistence saves the layout and function references.
+
+```python
+from meltygui.model.tile_model import Split, Tile
+
+@render_func(multi_instance=True, tint=(0.2, 0.4, 0.6))
+def draw_scene(input_value: Scene, state: ViewportState = None):
+    ...
+    return changed, input_value
+
+# Store this on your app model. A layout always has a Split root.
+app_model.tiles = Split("x", [
+    Tile(render_func=draw_scene, input_value=scene),
+    Tile(render_func=draw_scene, input_value=scene),
+])
+```
+
+The host declares `multi_instance_renderers=()` to receive the eligible
+function references from core, and passes that parameter to `draw_tiles` along
+with its injected `TileManagerState`. The selected editor receives the tile's
+input unchanged: the app supplies a compatible value, or the editor accepts
+`None` and uses injected model/state. Choosing another editor does not construct
+or convert model data.
+
+Each tile has independent injected view state. Switching editors and switching
+back restores that tile's editor state. Splitting inherits the renderer and
+shares the input value, while creating a new view instance. See
+`examples/tile_manager.py` for a runnable demo with counters and notes.
+
+### Sibling state parameters
+
+Each consuming tile gets one compact link-icon dropdown beside the tile switcher.
+The menu presents one column per injected parameter, with its name, required type,
+and eligible sources. Columns wrap on narrow displays. Selected rows have an
+outline, stronger fill and a fixed checkmark gutter so labels stay aligned.
+Selections leave the menu open; Escape or a click outside closes it.
+
+`[tile switcher] [chain · selected-source icons]`
+
+The trigger reserves one icon slot per parameter. Auto shows the resolved source
+icon; missing icons use a chain, and Self contained uses a database. Auto rows
+use a wand icon.
+
+Parameters come from the selected function's signature:
+
+```python
+from meltygui import DrawState, render_func
+
+@render_func()
+def draw_consumer(input_value, source: DrawState[draw_source] = None,
+                  selection: SelectionState = None):
+    ...
+    return changed, input_value
+```
+
+`DrawState[draw_source]` is a runtime framework annotation: `source` receives the
+actual draw state of the selected sibling instance of `draw_source`, or `None`
+when unlinked/unavailable. Declare/import the source function before using it in
+an annotation. The consumer's own `draw_state` parameter is unchanged. A source
+reference exists before either tile renders; geometry and body-produced fields
+reflect its latest render, so a newly created view has no rendered geometry yet.
+This convention is runtime metadata, not a standard static Python generic.
+
+A view can set `draw_state.nickname = "My instance"` to identify itself in link
+menus. Nicknames are display metadata: changing one never changes the unique ID,
+cache identity, or saved bindings. Leave it `None` to use the tile name. Source
+rows colour the renderer icon and subtly tint the text using the instance's
+`current_tint`, falling back
+to its renderer/tile tint before its first render. Duplicate nicknames retain a
+tile-ID suffix so distinct instances remain selectable.
+
+A `DictConversion` state parameter (default `None`, or without a default) offers
+compatible owned state from siblings. Unlinked state is still created locally
+by core. Linking borrows the source instance without changing its owner or
+replacing the consumer's retained local instance. State sources are the sibling's
+owned instances, not the instances it may itself borrow from another tile.
+
+Each parameter column lists **Auto**, eligible sibling sources in the same tile
+tree, then **Self contained** with a database icon. Self contained uses a private
+local state object, or `None` for a view reference. Existing manual and local settings are
+preserved. Auto chooses the source with the fewest parent/child edges through
+the tile tree, not pixel distance, so resizing cannot change its selection.
+Equal distances retain the current eligible source; without one, stable tile ID
+order breaks ties. Auto remains selected when there are no eligible sources and
+uses `None`/local state until a source becomes available. Manual choices stay pinned.
+
+Splitting copies the original tile's link settings, including Auto and settings
+for other renderers, into an independent dictionary on the new tile. It also
+inherits Auto's tie preference. The new tile keeps its own local state; editing
+its links does not change the original's links.
+
+Bindings persist by renderer, parameter, source tile ID and source parameter.
+Reordering a tile preserves its links. A missing or incompatible source is shown
+as **Source unavailable** and uses `None`/local state until restored or explicitly
+changed. Switching a consumer's renderer preserves that renderer's bindings for
+when it is selected again. Sources belong to the same `draw_tiles` tree; views
+don't need sibling traversal or registration code. Caller-supplied state also
+works outside tiles, including `source=some_draw_state`.
+
+Injected objects are cache dependencies: attribute edits invalidate consumers,
+including across cached frames. As elsewhere, report in-place edits with the
+view's `changed` result. See `examples/tile_sibling_links.py` for both annotation
+forms without changing any existing file-tree or editor view.
+
+Hosted renderers can declare `instance` and `layout_frame` parameters. These
+receive the tile's existing conversion identity and its four shared frame edges,
+so instance-targeted commands and nested column layouts stay within that tile.
+An editor created by a corner split first renders when the drag ends, after its
+initial size is known.
+
+Files in an installed library are read-only to the live editor. App source roots
+are registered from the app's entry point and decorated functions. An editable
+framework checkout can also be edited; an ordinary wheel in site-packages cannot.
+
+## Designing a feature
+
+**Locality.** Each thing lives next to what it belongs to, at the smallest scope that holds
+all of its users. Apply it to code, state, UI and lifetime, and let structure grow only when a
+second user appears somewhere else:
+
+- **Code**: a feature is one file in the app that uses it: its state class, its handful of
+  functions and its view together. Move a part into meltygui / meltygui_pro when a second app or
+  view needs it, or the package-split rules require it, and say what asked for it.
+- **State and config**: state lives on the thing it describes. View state is one injected
+  `DictConversion` per view (`@no_save` for process-lifetime fields); config a user edits lives
+  in the project it configures (`[tool.melty.<feature>]` in `pyproject.toml`), read the way the
+  app already reads it, in the flattest form that works; machine-local state lives in the
+  injected state or the file-meta store. Prefer plain data (`dict`, tuples, strings); add a class,
+  registry or service when two things must share it, not because a feature might grow.
+- **UI**: a feature appears beside the things it acts on and takes its context (project, file,
+  selection) from those neighbours, the way the app's most recent features do. It is built from
+  the widgets already here; menus and chords go in the app's entry module; both backends
+  identical.
+- **Lifetime**: what a feature starts (a process, a thread, a watch) belongs to it: stopped
+  by its own explicit action and at app exit, never as a side effect of something unrelated.
+  Background work is a daemon thread writing plain fields and calling `request_render()`, the
+  view invalidating while it runs; heavier machinery only when that pattern cannot do it.
+
+Older subsystems grew under different pressures; take proven recipes from them (spawning,
+streaming, waking the UI), not a new feature's shape.
+
+**A design doc is a page**: the state fields, the function signatures, the view, the build order,
+and a "later" list. The first version ships the core; extras wait in "later" until someone wants
+them. When a design genuinely needs more than this, say why in a sentence and go ahead.
+
+## Native binding imports
+
+MeltyGUI uses a namespaced ImGui binding. Low-level app code should use
+`from meltygui import imgui` (or `import meltygui_imgui as imgui`). Mixing contexts from
+upstream `imgui` with MeltyGUI's binding is unsupported. The upstream packages
+can coexist because the support wheels install different Python namespaces.
+
+The optional tensor backend similarly uses `meltygui_pycuda`. A child project's
+own `pycuda` dependency remains independent of MeltyGUI's internal backend.

{meltygui-0.1.0 → meltygui-0.1.3}/docs/DEVELOPMENT.md

@@ -7,16 +7,25 @@ remaining migration work and deliberate deferrals.
 
 ## Setup
 
-Supported targets are Linux x86-64 with CPython 3.11, 3.12 or 3.13 and a working
-OpenGL 4.3 context. MeltyGUI itself is not on PyPI yet, so install it from a
-checkout; its native support packages (`meltygui-imgui`, `meltygui-pycuda`) come
-from PyPI as prebuilt wheels:
+Linux x86-64 uses CPython 3.11, 3.12 or 3.13 and OpenGL 4.3. macOS on Apple
+Silicon is tested with CPython 3.12 and Apple's OpenGL 4.1 core context,
+including Retina font atlases and cached tiles. CUDA rendering requires an
+NVIDIA system and is unavailable on macOS.
+
+MeltyGUI itself is not on PyPI yet, so install it from a checkout. Native
+support packages come from PyPI; `meltygui-imgui` builds from source on macOS
+when no matching wheel is available, using Xcode Command Line Tools:
 
 ```sh
 uv venv --python 3.12
 uv pip install --python .venv/bin/python -e . --group dev
 ```
 
+On macOS, install `uv` with `brew install uv` if needed. Install Xcode Command
+Line Tools with `xcode-select --install` if they are not already available.
+The first native ImGui build can take a few minutes. No local `dist/release`
+directory is required.
+
 To use MeltyGUI from another project, add the checkout as a path dependency:
 
 ```sh
@@ -65,18 +74,43 @@ python3 tools/torch_matrix.py --window-smoke   # also opens the README example:
 Run apps with the environment's Python. The native Wayland and GLFW backends
 share the same render functions.
 
+macOS native resizing redraws through GLFW's window-refresh callback while
+Cocoa holds the event loop. The app only permits those frames during its OS
+event dispatch, restores the interrupted window's graphics contexts, and
+defers recursive refreshes and native window creation/destruction to the loop.
+When checking this path, drag the actual window border: programmatic size
+changes alone do not exercise Cocoa's live-resize loop.
+
 ```sh
 .venv/bin/pytest
 .venv/bin/python examples/tensor_live.py
 .venv/bin/python examples/voxel_playground.py
 ```
 
-Use `MELTY_BENCH=1` for a first-frame smoke run:
+Use `MELTY_BENCH=1` for a first-frame smoke run; it prints the start-up
+phase table (also appended to `~/.cache/<app_id>/startup.log` on every launch)
+and exits after the first frame:
 
 ```sh
 MELTY_BENCH=1 .venv/bin/python examples/tensor_live.py
 ```
 
+### Start-up
+
+The boot sequence is described at the top of `meltygui/core/runtime/app.py`
+and in the `meltygui` package docstring. An app's own imports run before its
+first `@glfw_window`; that decoration starts an import thread (the render
+libraries — imgui, numpy, OpenGL — and the GL side of the runtime) and opens
+the display on the calling thread, so the two overlap. The overlap is only real
+while the render graph stays light: `meltygui`, `core_render` and the views
+must not import the render libraries or the code-editing stack (libcst) at
+module level. The code stack loads with the first code edit — the inputs tab,
+a code view, a hotswap. `tests/test_startup_imports.py` pins this; when a
+change makes it fail, move the import into the function that needs it or,
+for a renderer of a code-stack type, register it by name
+(`is_default_for='CodeLine'`). Start-up workers belong in
+`meltygui.after_first_frame(fn)`, not in the first frame.
+
 Smoke-run every README example the same way (opens windows; run it from a
 reserved agent desktop):
 

meltygui-0.1.3/docs/INPUT_RECORDING.md

@@ -0,0 +1,81 @@
+# Input recording and replay
+
+Record what a user did in a MeltyGUI app; replay it against a fresh instance from
+outside, through the `hyprland-desktop` MCP server. Recording needs only
+MeltyGUI. Replay needs the MCP server and is run by melty-admin. This replaces new work on the Orchestrator, which
+stays in place and untouched.
+
+## Record
+
+| How | When |
+|---|---|
+| `MELTY_RECORD_INPUT=1` (or `=/path/file.input.jsonl`) | one launch, from the first frame |
+| `Toggles.InputRecording.record_on_launch = True` | every launch: crash reproduction, analytics |
+| the **Input Recorder** window's Record / Stop | a span inside a session; the Stop click is left out |
+| `draw_input_recorder(Melty.input_recorder)` | the same view inside your own app |
+
+Files land in `~/.cache/meltygui/input_recordings/` (newest
+`Toggles.InputRecording.keep_recordings` kept). A file is JSON lines, flushed as
+it is written, so the session that crashed is on disk up to the crash; the
+format is documented at the top of
+[input_recording_model.py](../meltygui/model/input_recording_model.py).
+`Toggles.InputRecording.record_typed_text = False` keeps typed text out.
+
+## Replay
+
+The front end is melty-admin's **Integration Tests** page and runner
+(`melty-admin/docs/INTEGRATION_TESTS.md`): **Record** there opens the editor on
+fresh state with `MELTY_RECORD_INPUT` set, and the session becomes the case
+`recording.<name>`, replayed on a reserved agent desktop with the suite's
+isolation, video and run history. MeltyGUI's part is knowing the recording:
+
+```python
+from meltygui.model.input_recording_model import InputRecording, compile_steps
+from meltygui.core.automation.input_replay import replay_steps
+recording = InputRecording.load(path)
+result = await replay_steps(desktop, compile_steps(recording.events), recording.windows())
+```
+
+`desktop` is any transport with `find_window(title)` and `call(tool, **arguments)`
+(the module docstring has the contract; melty-admin's is
+`melty_integration/recorded.py`). `python -m meltygui.core.automation.input_replay
+RECORDING` prints the compiled steps and needs no server.
+
+A replay only reproduces a session that starts where the recording started:
+launch both on the same document with empty `XDG_STATE_HOME`, `XDG_CACHE_HOME`,
+`XDG_CONFIG_HOME` and `XDG_DATA_HOME`, which is what the page's Record does.
+
+How a step is made reliable: each OS window is found by its title and resized to
+the recorded content size; a click on a control that published its text
+(`Melty.effect_hook("button", ..., text=label)`: `flat_button`, `draw_button`)
+is placed by OCR within 120 px of the recorded point, and falls back to the
+recorded point when OCR cannot read it. Everything else replays by coordinate.
+
+## Where the code lives
+
+| File | Owns |
+|---|---|
+| `core/input/input_handler.py` | `add_input_observer`: passive listeners on the one input funnel |
+| `core/melty.py` | `Melty.input_recorder`; `Melty.effect_hook` fans out to `effect_listeners` |
+| `model/input_recording_model.py` | `InputRecorder` (queue + writer thread), `InputRecording`, `compile_steps` (pure) |
+| `view/input_recording_view.py` | `draw_input_recorder(input_value: InputRecorder)` |
+| `core/automation/input_recording_core.py` | wiring: window probe, Toggles, record on launch, window registration |
+| `core/automation/input_replay.py` | recording -> MCP `batch` steps, sent over any transport; never imported by the app |
+
+## Frame cost
+
+The observer list is empty unless a recording runs: idle cost is one truthiness
+check per input event (0.09 µs). While recording, an event costs a tuple and a
+`SimpleQueue.put` on the input callback (1.0 µs measured, with at most one cursor
+sample per frame: about 0.01 % of the 8.3 ms budget); JSON encoding and file
+writes happen on the writer thread. Replay and OCR run in another process.
+
+## Known limits
+
+- Bare cursor travel is not replayed, so hover-only UI (tooltips, hover menus)
+  is not reproduced. Space-mouse axes are not recorded.
+- Replay coordinates assume the compositor's window geometry is the content
+  (true for the native Wayland backend, verified). The GLFW backend is unverified.
+- One MCP wheel notch is 1.5 scroll units here (`SCROLL_UNITS_PER_NOTCH`).
+- A replay reports only whether every step ran; the end state is for the
+  test (or the video) to judge.

{meltygui-0.1.0 → meltygui-0.1.3}/docs/PUBLISHING.md

@@ -1,6 +1,6 @@
-# Publishing the first release
+# Publishing a release
 
-Artifacts are prepared and locally verified. They have not been uploaded.
+`meltygui` 0.1.0 was published on 2026-09-18 through the workflow below.
 
 ## Required account decisions
 
@@ -43,6 +43,27 @@ entire `dist` tree. The latter also contains older experimental artifacts.
 `SHA256.json` records the intended uploads. Never reuse a published version for
 changed files; bump the relevant core or support-package version.
 
+### From Thermostat
+
+The top **Deployment checklist** has **Prepare deployment** and **Deploy**. Preparation synchronizes
+all three package versions and MeltyGUI's native requirements, optionally commits/pushes the release
+edits, verifies native builds, and runs MeltyGUI's installation tests with support wheels.
+Existing changes must first be reviewed and pushed. Deploy rechecks the tested source commits and
+publishes ImGui, PyCUDA, then MeltyGUI, waiting for each native release to reach PyPI.
+The `imgui_run_id` and `pycuda_run_id` workflow inputs identify successful native builds. During
+verification, their public source commits are checked out and rebuilt into staged wheels; this needs
+no credential for cross-repository artifact downloads. Already published native releases and all
+publication runs install support wheels from PyPI. GPU execution still needs separate hardware validation.
+
+Individual controls remain available:
+
+Use Deployments → **Raise version** when needed → **Review / commit / push** →
+**Verify build** → **Publish**. The review button opens the repository's Version
+Control card. The UI distinguishes failed, unverified and verified source;
+confirmations carry the displayed version and source commit. The workflow's
+optional `expected_version` and `expected_sha` inputs validate that version and
+pin checkout to the confirmed source. Manual GitHub runs may leave both blank.
+
 ## Acceptance after upload
 
 Use a new environment for each supported Python (3.11, 3.12, 3.13) with no local find-links or extra index:
@@ -55,4 +76,4 @@ uv pip install --python /tmp/meltygui-from-pypi/bin/python meltygui
 
 Then launch a child app and check `meltygui[tensor]` on a supported NVIDIA machine.
 A local install using `--find-links` validates the artifacts, not public PyPI
-availability. Public acceptance remains pending until that final check passes.
+availability. 0.1.0 passed the fresh-install check on Linux (3.11-3.13) and Windows (3.12).

meltygui-0.1.3/examples/render_overlay.py

@@ -0,0 +1,36 @@
+"""A live overlay on a frozen blit tile. Resize the window to try it."""
+import time
+
+import meltygui
+from meltygui import imgui, render_func
+from meltygui.core.runtime.toggles import Tint
+from meltygui.core.windowing.glfw_utils import request_render
+from meltygui.hdr_color import pack_color
+
+
+def draw_clock(draw_state, draw_list):
+    # Use live geometry and the supplied list: neither this text nor its
+    # changing position is captured in the body's tile.
+    x = draw_state._abs_left() + 12
+    y = draw_state._abs_top() + draw_state.header_height + 12
+    color = pack_color(*Tint.dd_text(draw_state.current_tint), 1.0)
+    draw_list.add_text(x, y, color, f'Live overlay: {time.monotonic():.2f}')
+
+
+@render_func(use_cache=True, freeze_resize=True, draw_overlay=draw_clock,
+             tint=(0.20, 0.30, 0.42), show_bg=True, auto_resize=False)
+def draw_cached_panel(input_value: str, draw_state=None):
+    imgui.get_window_draw_list().add_text(
+        draw_state.abs_left + 12, draw_state.abs_top + 70,
+        pack_color(*Tint.dd_text(draw_state.current_tint), 1.0), input_value)
+    return False, input_value
+
+
+@meltygui.glfw_window(name='Render overlays', app_id='meltygui-render-overlay-demo',
+                     width=720, height=420)
+@render_func(tint=(0.20, 0.30, 0.42), determines_height=False)
+def overlay_demo(input_value: object = None, draw_state=None):
+    # A clock animates even without input; ordinary overlays can let the app idle.
+    request_render()
+    return draw_cached_panel('This body is cached. The clock draws every frame.',
+                             width=draw_state.width, height=draw_state.height)