pycodecad 1.0.0__py3-none-any.whl

pycodecad/cli.py

@@ -0,0 +1,241 @@
+"""Command line: open the window, or check/render/export a script without it.
+
+    pycodecad file.py [--read-only] [--no-run]           window on the file's folder, file.py runs (created if missing)
+    pycodecad folder/                                    window on a folder (its part runs: see workspace.find_main)
+    pycodecad examples [folder]                          copy the examples there once (default ./pycodecad-examples), open it
+    pycodecad check file.py                              run it, print the result as JSON
+    pycodecad render file.py out.png [--views iso | iso,front,top | window] [--size 800x600] [--frame N]
+    pycodecad export file.py out.stl [--profile bambu]   also .3mf .step .glb .brep
+    pycodecad context file.py                            print the AI context
+
+check, render and export take --set KEY=VALUE (repeatable) for the parameters of expose():
+KEY is "param" or "function.param".
+
+Ctrl+C (or SIGTERM/SIGHUP) stops the running script and exits with code 130.
+"""
+from __future__ import annotations
+
+import argparse
+import contextlib
+import json
+import os
+import shutil
+import signal
+import sys
+from pathlib import Path
+
+from . import __version__
+
+COMMANDS = ("check", "render", "export", "context")
+
+
+class Usage(Exception):
+    """A command line that cannot work: the message is printed and pycodecad exits with 1."""
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = sys.argv[1:] if argv is None else argv
+    for stream in (sys.stdout, sys.stderr):  # a console that is not UTF-8 (Windows): never fail to print
+        if hasattr(stream, "reconfigure"):
+            stream.reconfigure(errors="backslashreplace")  # pyright: ignore[reportAttributeAccessIssue]
+    stops = [number for number in (signal.SIGTERM, getattr(signal, "SIGHUP", None)) if number is not None]
+    previous = {number: signal.signal(number, interrupt) for number in stops}
+    try:
+        from .cad import remove_stale_temp
+
+        remove_stale_temp()
+        if argv and argv[0] in COMMANDS:
+            return command(argv[0], argv[1:])
+        if argv and argv[0] == "examples":
+            return examples(argv[1:])
+        return window(argv)
+    except KeyboardInterrupt:  # the run (if any) is already killed
+        print("pycodecad: interrupted", file=sys.stderr)
+        return 130
+    except (OSError, Usage) as exc:
+        from .sidecar import error_text
+
+        print(f"pycodecad: {error_text(exc) if isinstance(exc, OSError) else exc}", file=sys.stderr)
+        return 1
+    finally:
+        for number, handler in previous.items():
+            signal.signal(number, handler)
+
+
+def interrupt(number, frame) -> None:
+    raise KeyboardInterrupt
+
+
+def window(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(prog="pycodecad", description="Code-CAD window for build123d scripts. "
+                                     "Other commands: pycodecad {check,render,export,context,examples} --help")
+    parser.add_argument("file", help="script to run (created if it does not exist), or a folder")
+    parser.add_argument("--read-only", action="store_true", help="an order form: parameters, Run and Export, no "
+                        "code; scripts are never written")
+    parser.add_argument("--no-run", action="store_true", help="do not run the script when the window opens")
+    parser.add_argument("--screenshot", metavar="PNG", help="save a picture of the window after the first run and quit")
+    parser.add_argument("--version", action="version", version=f"pycodecad {__version__}")
+    options = parser.parse_args(argv)
+    from .app import open_window
+
+    open_window(options.file, screenshot=options.screenshot, read_only=options.read_only, run=not options.no_run)
+    return 0
+
+
+def examples(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(prog="pycodecad examples", description="Copy the examples into a folder the "
+                                     "first time, then open the window on it (an existing folder is opened as it is).")
+    parser.add_argument("folder", nargs="?", default="pycodecad-examples", help="default ./pycodecad-examples")
+    parser.add_argument("--no-run", action="store_true", help="do not run the script when the window opens")
+    options = parser.parse_args(argv)
+    target = Path(options.folder)
+    if not target.exists():
+        shutil.copytree(bundled_examples(), target, ignore=shutil.ignore_patterns("__pycache__", ".pycodecad"))
+        print(f"Copied the examples to {target.resolve()}")
+    from .app import open_window
+
+    open_window(str(target), run=not options.no_run)
+    return 0
+
+
+def bundled_examples() -> Path:
+    """The examples inside the installed package, or next to the sources in a checkout."""
+    for folder in (Path(__file__).parent / "examples", Path(__file__).parents[2] / "examples"):
+        if folder.is_dir():
+            return folder
+    raise Usage("the examples are not installed with this copy of pycodecad")
+
+
+def command(name: str, argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(prog=f"pycodecad {name}", allow_abbrev=False)
+    parser.add_argument("file", help="the script")
+    if name == "render":
+        parser.add_argument("output", help="PNG file to write")
+        parser.add_argument("--views", default="iso", help="iso (default), front, back, left, right, top or "
+                            "bottom; several make a labeled grid (iso,front,top,right); window is the camera of "
+                            "the open window")
+        parser.add_argument("--size", help="WIDTHxHEIGHT of each view (default 800x600, or the window's)")
+        parser.add_argument("--frame", type=int, metavar="N", help="frame N (1, 2, ...) of an animation made "
+                            "with frame(); by default the scene at the end of the script")
+    if name == "export":
+        parser.add_argument("output", help="file to write: .stl .3mf .step .glb or .brep")
+        from .files import PROFILES
+
+        parser.add_argument("--profile", choices=PROFILES, help="3MF flavor (default generic)")
+    if name != "context":
+        parser.add_argument("--set", action="append", default=[], type=setting, metavar="KEY=VALUE",
+                            help="value of an exposed parameter (\"param\" or \"function.param\"); repeatable")
+    options = parser.parse_args(argv)
+    script = Path(options.file).resolve()
+    from .sidecar import read_script
+
+    picture = render_plan(script, options) if name == "render" else None
+    if name == "export":
+        check_export(options)
+    code = read_script(script)
+    from . import runner
+
+    export = str(Path(options.output).resolve()) if name == "export" else None
+    values = dict(getattr(options, "set", []))
+    run = runner.Run(code, str(script), export=export, profile=getattr(options, "profile", None) or "generic",
+                     values=values)
+    try:
+        result = run.wait()
+    except KeyboardInterrupt:
+        run.kill()
+        with contextlib.suppress(TimeoutError):
+            run.wait(5)  # its last-run file says "Stopped"
+        raise
+    if name == "check":
+        print(json.dumps(runner.report(str(script), result), indent=2))
+        return 1 if result.error else 0
+    if name == "context":
+        from .context import ai_context
+
+        print(ai_context(script, result))
+        return 0
+    if result.stdout and name == "export":
+        print(result.stdout, end="")
+    if result.error:
+        print(result.error, file=sys.stderr)
+        return 1
+    frame = getattr(options, "frame", None)
+    if frame is not None and not 1 <= frame <= len(result.frames):
+        raise Usage(f"--frame {frame}: the script made {len(result.frames)} frames (frame() calls)")
+    if not result.shown and not frame:
+        raise Usage("nothing shown: call show() in the script")
+    if name == "export":
+        print(f"Wrote {result.exported}")
+        return 0
+    assert picture is not None  # name == "render": planned before running
+    return render(result.frames[frame - 1] if frame else result.shown, options.output, *picture)
+
+
+def setting(text: str) -> tuple[str, str]:
+    """--set KEY=VALUE: the value stays a string, converted by expose() to the parameter's type."""
+    key, equals, value = text.partition("=")
+    if not equals or not key.strip():
+        raise argparse.ArgumentTypeError(f"must look like KEY=VALUE (width=80 or box.width=80), not {text!r}")
+    return key.strip(), value
+
+
+def check_output(output: str) -> None:
+    folder = Path(output).resolve().parent
+    if not folder.is_dir():
+        raise Usage(f"the folder of {output} does not exist: {folder}")
+
+
+def check_export(options) -> None:
+    from .files import FORMATS
+
+    kind = Path(options.output).suffix.lower().lstrip(".")
+    if kind not in FORMATS:
+        raise Usage(f"cannot export {options.output}: use one of .{', .'.join(FORMATS)}")
+    if options.profile and kind != "3mf":
+        raise Usage("--profile is only for .3mf files")
+    check_output(options.output)
+
+
+def render_plan(script: Path, options) -> tuple[list, tuple[int, int]]:
+    """The views (names or the window's Camera) and the size of each, checked before running."""
+    from .camera import check_view
+    from .renderer import check_size
+    from .sidecar import load_camera
+
+    if Path(options.output).suffix.lower() != ".png":
+        raise Usage(f"render writes PNG pictures: {options.output} must end in .png")
+    check_output(options.output)
+    size = (800, 600)
+    if options.size:
+        try:
+            width, height = (int(value) for value in options.size.lower().split("x"))
+            size = (width, height)
+            check_size(size)
+        except ValueError:
+            raise Usage(f"--size must look like 800x600 (1 to 8192 pixels per side), not {options.size}") from None
+    views: list = options.views.split(",")
+    for view in views:
+        try:
+            check_view(view, "window")
+        except ValueError as exc:
+            raise Usage(str(exc)) from None
+    if "window" in views:
+        if len(views) > 1:
+            raise Usage("--views window shows the window camera alone: do not combine it with other views")
+        try:
+            camera, window_size = load_camera(script)
+        except (OSError, ValueError):
+            raise Usage(f"no window camera saved for {script.name} yet: open it with "
+                        f"`pycodecad {script.name}` and move the view") from None
+        views = [camera]
+        if options.size is None:
+            size = window_size
+    return views, size
+
+
+def render(shown: list, output: str, views: list, size: tuple[int, int]) -> int:
+    from .renderer import png_bytes, render_views
+
+    Path(output).write_bytes(png_bytes(render_views(shown, views, size)))
+    print(f"Wrote {Path(output).resolve()}")
+    return 0

pycodecad/context.py

@@ -0,0 +1,178 @@
+"""The "AI context": a text to paste into an AI assistant so it can build and iterate on the part.
+
+Used by the "Copy AI context" button and by `pycodecad context file.py`.
+"""
+from __future__ import annotations
+
+import shlex
+import shutil
+import sys
+from pathlib import Path
+
+from . import __version__
+
+SKIP = {"__pycache__", "venv", ".venv", "node_modules"}
+MAX_FILES = 60
+WINDOWS = sys.platform == "win32"
+
+GUIDE = """\
+## How pycodecad runs a script
+- `{pycodecad} {file}` runs it in the window; `python {file}` runs it without one (show(), clear() and frame()
+  then do nothing).
+- A part always starts from its own folder, so it works on any PC: keep the script, its helper
+  modules and its assets together in one folder and use relative paths, never absolute ones
+  (/home/...). With plain `python`, relative paths start from the current directory: for files
+  that must also work that way use `Path(__file__).parent / "name"`.
+- Every run (window, check, render, export) writes its result to .pycodecad/{name}.last-run.json
+  next to the script (same JSON as `check`): read it to see the latest error.
+
+## Workflow
+- Edit the file directly. The window runs the script once when it opens, then never reloads or
+  runs by itself: it shows "Changed on disk" and the owner presses Reload and Run.
+- Check your work from a terminal in that folder (each command runs the script fresh, no window):
+    {pycodecad} check {file}        # JSON: ok, error, where (file:line), traceback, stdout, objects
+    {pycodecad} render {file} out.png --views iso,front,top,right   # then look at out.png
+    {pycodecad} render {file} out.png --views window                # exactly what the owner sees
+    {pycodecad} render {file} out.png --set width=80                # other values for expose()
+    {pycodecad} export {file} {stl}    # also .3mf .step .glb .brep; --profile bambu (Bambu Studio 3MF)
+- Helper modules: write helper.py next to the script and `import helper` (fresh on every run).
+
+## pycodecad API (docs: https://github.com/offerrall/pycodecad/tree/v{version}/docs)
+`from pycodecad import show, clear, frame, import_mesh, expose`
+The script says what is in the scene with show(); the window, check, render and export all look
+at that same scene. Nothing is shown without show().
+- show(*objs, name=None, color=None): add shapes/builders/lists to the scene. color: "#RRGGBB",
+  a name ("red", "gold"...) or an RGB triple.
+- clear(): empty the scene.
+- frame(): save the scene now as the next frame of an animation (30/s; the window plays them).
+  Build parts once and move them with Pos/Rot per frame (not recomputed); hold = call frame() again.
+  `{pycodecad} render {file} out.png --frame N` draws frame N (1-based); check reports "frames".
+- import_mesh(path, solid=False, max_faces=5000): STL/3MF as a fast mesh for show/export;
+  solid=True gives a build123d Solid for booleans (small closed meshes only).
+- expose(fn): calls fn and returns its result; the window shows a control per parameter (Run
+  applies them). Only int/float/bool/str parameters with a default, annotated only with pytypehint
+  Min, Max, Step, Slider, Label, Description: `def box(width: Annotated[float, Min(20.0),
+  Max(200.0), Slider()] = 60.0)`, then `show(expose(box))`. Without the window the defaults are
+  used, or `--set width=80` (or `box.width=80`) on check/render/export.
+
+## build123d essentials (docs: https://build123d.readthedocs.io), units mm, Z up
+```python
+from build123d import *
+from pycodecad import show
+
+# Algebra style: shapes are values; + union, - cut, & intersect; Pos/Rot place them.
+plate = Box(60, 40, 5, align=(Align.CENTER, Align.CENTER, Align.MIN))  # sits on Z=0
+plate -= Pos(20, 10, 0) * Cylinder(3, 20)            # through hole
+plate = fillet(plate.edges().filter_by(Axis.Z), radius=4)
+
+# Builder style: 2D sketch on a plane, then extrude.
+with BuildPart() as bracket:
+    with BuildSketch(Plane.XY):
+        RectangleRounded(40, 20, 3)
+        with Locations((-12, 0), (12, 0)):
+            Circle(2.5, mode=Mode.SUBTRACT)
+    extrude(amount=4)
+    chamfer(bracket.edges().group_by(Axis.Z)[-1], length=0.8)  # top edges
+
+show(Pos(0, 50, 0) * plate, name="plate", color="#F4B02A")
+show(bracket, name="bracket")
+```
+- Primitives are centered on their location by default; use `align=` to put a face on a plane.
+- Edge/face selection: `.edges().filter_by(Axis.Z)`, `.faces().sort_by(Axis.Z)[-1]` (top face),
+  `.group_by(Axis.Z)[-1]`. Apply fillets/chamfers last; a radius too big for a wall fails.
+- Other useful pieces: Text("ABC", font_size=8) in a BuildSketch, revolve(), loft(), sweep(),
+  PolarLocations(r, n), GridLocations(dx, dy, nx, ny), mirror(about=Plane.YZ), offset(), import_svg().
+"""
+
+
+def quote(text: str) -> str:
+    """A literal argument for PowerShell on Windows, or a POSIX shell elsewhere."""
+    return "'" + text.replace("'", "''") + "'" if WINDOWS else shlex.quote(text)
+
+
+def pycodecad_command() -> str:
+    """How to call this pycodecad from a terminal."""
+    script = Path(sys.executable).with_name("pycodecad.exe" if WINDOWS else "pycodecad")
+    if script.exists():
+        if shutil.which("pycodecad") == str(script):
+            return "pycodecad"
+        command = quote(str(script))
+    else:
+        command = f"{quote(sys.executable)} -m pycodecad"
+    return "& " + command if WINDOWS else command
+
+
+def size_text(size: float) -> str:
+    if size < 1024:
+        return f"{size:.0f} B"
+    return f"{size / 1024:.1f} KB" if size < 1024**2 else f"{size / 1024**2:.1f} MB"
+
+
+def folder_listing(folder: Path) -> list[str]:
+    """Files of the folder and its subfolders (two levels), with sizes."""
+    lines = []
+    for path in sorted(folder.glob("*")) + sorted(folder.glob("*/*")):
+        relative = path.relative_to(folder)
+        if any(part.startswith(".") or part in SKIP for part in relative.parts) or not path.is_file():
+            continue
+        lines.append(f"  {relative.as_posix()} ({size_text(path.stat().st_size)})")
+    if len(lines) > MAX_FILES:
+        lines = lines[:MAX_FILES] + [f"  ... and {len(lines) - MAX_FILES} more"]
+    return lines
+
+
+def state_lines(state) -> list[str]:
+    """State: anything with shown, error, error_file, error_line, warnings and stdout (Workspace or runner.Result)."""
+    lines = []
+    for obj in state.shown:
+        bbox = obj.bbox()
+        size = " x ".join(f"{hi - lo:.4g}" for lo, hi in zip(*bbox)) if bbox else "empty"
+        position = ", ".join(f"{(lo + hi) / 2:.4g}" for lo, hi in zip(*bbox)) if bbox else "-"
+        volume = f", volume {obj.volume:.6g} mm³" if obj.volume is not None else ""
+        lines.append(f"- {obj.name}: size {size} mm, center ({position}){volume}")
+    if not lines:
+        lines.append("- no objects")
+    if state.error:
+        where = f" in {state.error_file}, line {state.error_line}" if state.error_file else ""
+        lines.append(f"Error{where}:\n```\n{state.error.strip()[-2000:]}\n```")
+    for warning in state.warnings:
+        lines.append(f"Warning: {warning}")
+    if state.stdout.strip():
+        lines.append(f"Script output:\n```\n{state.stdout.strip()[-1500:]}\n```")
+    return lines
+
+
+def parameter_lines(exposed) -> list[str]:
+    """The parameters of the exposed functions (params.Exposed) with the values the run used."""
+    lines = []
+    for group in exposed:
+        lines.append(f"- {group.function}():")
+        for param in group.params:
+            limits = "length " if param.kind == "str" and (param.min is not None or param.max is not None) else ""
+            if param.min is not None or param.max is not None:
+                low = "" if param.min is None else f"{param.min:g}"
+                high = "" if param.max is None else f"{param.max:g}"
+                limits += f"{low}..{high}"
+            extras = [param.kind, limits, param.step is not None and f"step {param.step:g}",
+                      param.slider and "slider", param.label and f"label {param.label!r}",
+                      param.value != param.default and f"default {param.default!r}"]
+            text = f"  - {param.name} = {param.value!r} ({', '.join(filter(None, extras))})"
+            lines.append(text + (f": {param.description}" if param.description else ""))
+    return lines
+
+
+def ai_context(path: Path, state=None) -> str:
+    """The whole text. path: the script; state: see state_lines."""
+    head = ["# pycodecad: code-CAD with build123d",
+            f"A pycodecad window shows in 3D what `{path.name}` builds.",
+            f"Folder: {path.parent}", f"File: {path}", "Files in the folder:", *folder_listing(path.parent)]
+    if WINDOWS:
+        head += ["", "Run the commands below in PowerShell."]
+    if state is not None:
+        head += ["", "## Current state", *state_lines(state)]
+        exposed = getattr(state, "parameters", None) or []
+        if exposed:
+            head += ["", "## Exposed parameters (values of the last run)", *parameter_lines(exposed)]
+    commands = dict(file=quote(path.name), name=path.name, stl=quote(path.stem + ".stl"),
+                    pycodecad=pycodecad_command(), version=__version__)
+    return "\n".join(head) + "\n\n" + GUIDE.format(**commands)

pycodecad/editor.py

@@ -0,0 +1,256 @@
+"""The code editor widget: Python highlighting and keyboard/mouse editing, drawn with ImGui."""
+from __future__ import annotations
+
+import builtins
+import io
+import keyword
+import tokenize
+from dataclasses import replace
+from functools import lru_cache
+
+import glfw
+from slimgui import imgui
+
+from . import textedit
+from .imgui_backend import clipboard_text
+from .textedit import Editor
+
+COLORS = {
+    "text": (0.84, 0.87, 0.91, 1.0),
+    "keyword": (0.79, 0.57, 0.95, 1.0),
+    "builtin": (0.42, 0.77, 0.96, 1.0),
+    "string": (0.66, 0.82, 0.52, 1.0),
+    "number": (0.96, 0.71, 0.42, 1.0),
+    "comment": (0.48, 0.59, 0.65, 1.0),
+    "decorator": (0.95, 0.78, 0.42, 1.0),
+    "definition": (0.98, 0.85, 0.56, 1.0),
+    "cad": (0.32, 0.84, 0.75, 1.0),
+}
+CAD_NAMES = frozenset("""
+Box Cylinder Sphere Cone Torus Wedge BuildPart BuildSketch BuildLine
+Part Sketch Solid Face Wire Edge Vertex Compound Location Locations
+PolarLocations GridLocations HexLocations Plane Axis Vector Color
+Align Mode GeomType Rectangle RectangleRounded Circle Ellipse Polygon
+RegularPolygon Polyline Line Spline Bezier RadiusArc CenterArc ThreePointArc
+fillet chamfer extrude revolve loft sweep offset mirror scale split
+make_face make_hull add subtract intersect Pos Rot show clear import_mesh render
+""".split())
+BUILTINS = frozenset(dir(builtins))
+SELECTION = (0.25, 0.48, 0.78, 0.45)
+CURRENT_LINE = (0.8, 0.85, 1.0, 0.045)
+ERROR_LINE = (0.8, 0.2, 0.2, 0.23)
+
+
+@lru_cache(maxsize=16)
+def highlight(text: str) -> tuple[tuple[tuple[str, str], ...], ...]:
+    """Per line, (text, kind) spans covering the whole line; works on incomplete code too."""
+    lines = text.split("\n")
+    kinds = [["text"] * len(line) for line in lines]
+
+    def paint(start: tuple[int, int], end: tuple[int, int], kind: str) -> None:
+        for row in range(max(1, start[0]), min(len(lines), end[0]) + 1):
+            lo = start[1] if row == start[0] else 0
+            hi = min(end[1] if row == end[0] else len(lines[row - 1]), len(lines[row - 1]))
+            kinds[row - 1][lo:hi] = [kind] * max(0, hi - lo)
+
+    definition = decorator = False
+    try:
+        for token in tokenize.generate_tokens(io.StringIO(text).readline):
+            kind = "text"
+            if token.type == tokenize.NAME:
+                if definition:
+                    kind, definition = "definition", False
+                elif keyword.iskeyword(token.string) or keyword.issoftkeyword(token.string):
+                    kind, definition = "keyword", token.string in ("class", "def")
+                elif decorator:
+                    kind = "decorator"
+                elif token.string in CAD_NAMES:
+                    kind = "cad"
+                elif token.string in BUILTINS:
+                    kind = "builtin"
+            elif token.type == tokenize.STRING or tokenize.tok_name[token.type].startswith("FSTRING"):
+                kind = "string"
+            elif token.type == tokenize.NUMBER:
+                kind = "number"
+            elif token.type == tokenize.COMMENT:
+                kind = "comment"
+            elif token.string == "@" and not lines[token.start[0] - 1][:token.start[1]].strip():
+                decorator, kind = True, "decorator"
+            if token.type in (tokenize.NEWLINE, tokenize.NL) or token.string == "(":
+                decorator = False
+            paint(token.start, token.end, kind)
+    except (tokenize.TokenError, SyntaxError) as exc:
+        if isinstance(exc, tokenize.TokenError) and "multi-line string" in exc.args[0]:
+            paint(exc.args[1], (len(lines), len(lines[-1])), "string")
+    result = []
+    for line, styles in zip(lines, kinds):
+        spans = []
+        start = 0
+        while start < len(line):
+            end = start + 1
+            while end < len(line) and styles[end] == styles[start]:
+                end += 1
+            spans.append((line[start:end], styles[start]))
+            start = end
+        result.append(tuple(spans))
+    return tuple(result)
+
+
+def _column(line: str, x: float, char_width: float) -> int:
+    """Character index under a horizontal pixel offset (tabs are 4 columns wide)."""
+    target = max(0.0, x / char_width)
+    visual = 0
+    for index, char in enumerate(line):
+        following = visual + (4 - visual % 4 if char == "\t" else 1)
+        if target < (visual + following) / 2:
+            return index
+        visual = following
+    return len(line)
+
+
+MOVES = {  # key -> (textedit key, with Ctrl)
+    glfw.KEY_LEFT: ("left", "word_left"), glfw.KEY_RIGHT: ("right", "word_right"),
+    glfw.KEY_UP: ("up", "up"), glfw.KEY_DOWN: ("down", "down"),
+    glfw.KEY_HOME: ("home", "doc_start"), glfw.KEY_END: ("end", "doc_end"),
+    glfw.KEY_PAGE_UP: ("page_up", "page_up"), glfw.KEY_PAGE_DOWN: ("page_down", "page_down"),
+    glfw.KEY_BACKSPACE: ("backspace", "word_backspace"), glfw.KEY_DELETE: ("delete", "word_delete"),
+}
+
+
+def copy_text(text: str) -> None:
+    """Put text on the system clipboard."""
+    glfw.set_clipboard_string(None, text)  # pyright: ignore[reportArgumentType]  # GLFW takes None; its stub does not
+
+
+def _keyboard(editor: Editor, events: list, page_lines: int, focused: bool = True) -> Editor:
+    """Apply typed text and editing keys (only when focused) and call the window's actions (see
+    ui.shortcuts), all in the order they arrived."""
+    for event in events:
+        if callable(event):
+            event(editor)
+        elif focused and isinstance(event, str):
+            editor = textedit.insert(editor, event, typing=True)
+        if callable(event) or not focused or isinstance(event, str):
+            continue
+        key, mods, repeat = event
+        ctrl, shift = bool(mods & glfw.MOD_CONTROL), bool(mods & glfw.MOD_SHIFT)
+        if key in MOVES:
+            editor = textedit.key(editor, MOVES[key][ctrl], shift, page_lines)
+        elif key == glfw.KEY_TAB:
+            editor = textedit.key(editor, "untab" if shift else "tab")
+        elif key in (glfw.KEY_ENTER, glfw.KEY_KP_ENTER) and not ctrl:
+            editor = textedit.key(editor, "enter")
+        elif not ctrl:
+            continue
+        elif key == glfw.KEY_Z:
+            editor = textedit.redo(editor) if shift else textedit.undo(editor)
+        elif key == glfw.KEY_Y:
+            editor = textedit.redo(editor)
+        elif key == glfw.KEY_V:
+            editor = textedit.insert(editor, clipboard_text())
+        elif repeat:
+            continue
+        elif key == glfw.KEY_A:
+            editor = textedit.key(editor, "select_all")
+        elif key == glfw.KEY_C:
+            lo, hi = textedit.copy_range(editor)
+            copy_text(editor.text[lo:hi])
+        elif key == glfw.KEY_X:
+            editor, text = textedit.cut(editor)
+            copy_text(text)
+    return editor
+
+
+def view(editor: Editor, size: tuple[float, float], events: list, error_line: int | None,
+         wheel_scroll: bool = True) -> Editor:
+    """Draw the visible lines and handle input (when focused). Returns the (maybe) edited editor.
+    wheel_scroll False: the mouse wheel does not scroll (Ctrl+wheel zooms instead)."""
+    flags = imgui.WindowFlags.HORIZONTAL_SCROLLBAR
+    if not wheel_scroll:
+        flags |= imgui.WindowFlags.NO_SCROLL_WITH_MOUSE
+    visible = imgui.begin_child("editor", size, imgui.ChildFlags.NONE, flags)
+    try:
+        if not visible:
+            return _keyboard(editor, events, 1, focused=False)
+        lines = editor.text.split("\n")
+        spans = highlight(editor.text)
+        height = imgui.get_text_line_height_with_spacing()
+        char_width = imgui.calc_text_size("M" * 64)[0] / 64  # one character is rounded up; zoomed sizes are fractional
+        gutter = char_width * (len(str(len(lines))) + 2)
+        origin = imgui.get_cursor_screen_pos()
+        available = imgui.get_content_region_avail()
+        longest = max(len(line.expandtabs(4)) for line in lines)
+        content_width = max(gutter + (longest + 2) * char_width, available[0])
+        imgui.invisible_button("##source", (content_width, max(len(lines) * height, available[1])))
+        hovered, active = imgui.is_item_hovered(), imgui.is_item_active()
+        io_state = imgui.get_io()
+
+        # Mouse: click places the cursor, drag selects (scrolling at the borders), 2/3 clicks select word/line.
+        clicked = hovered and imgui.is_mouse_clicked(imgui.MouseButton.LEFT)
+        dragging = active and imgui.is_mouse_dragging(imgui.MouseButton.LEFT)
+        if clicked or dragging:
+            imgui.set_window_focus()
+            x, y = io_state.mouse_pos
+            row = max(0, min(len(lines) - 1, int((y - origin[1]) / height)))
+            column = _column(lines[row], x - origin[0] - gutter, char_width)
+            clicks = max(1, imgui.get_mouse_clicked_count(imgui.MouseButton.LEFT)) if clicked else 1
+            editor = textedit.click(editor, row, column, extend=io_state.key_shift or not clicked, clicks=clicks)
+            if dragging:
+                (left, top), (width, window_height) = imgui.get_window_pos(), imgui.get_window_size()
+                if not top <= y <= top + window_height:
+                    imgui.set_scroll_y(max(0.0, imgui.get_scroll_y() + (y - top if y < top else y - top - window_height)))
+                if not left <= x <= left + width:
+                    imgui.set_scroll_x(max(0.0, imgui.get_scroll_x() + (x - left if x < left else x - left - width)))
+        if hovered:
+            imgui.set_mouse_cursor(imgui.MouseCursor.TEXT_INPUT)
+
+        focused = imgui.is_window_focused()
+        editor = _keyboard(editor, events, max(1, int(size[1] / height) - 1), focused)
+        if editor.text != "\n".join(lines):
+            lines = editor.text.split("\n")
+            spans = highlight(editor.text)
+
+        row, col = textedit.line_col(editor.text, editor.cursor)
+        cursor_x = gutter + len(lines[row][:col].expandtabs(4)) * char_width
+        cursor_y = row * height
+        if editor.reveal:  # scroll the cursor into view once
+            scroll_x, scroll_y = imgui.get_scroll_x(), imgui.get_scroll_y()
+            window_w, window_h = imgui.get_window_size()
+            if cursor_y < scroll_y or cursor_y + 2 * height > scroll_y + window_h:
+                imgui.set_scroll_y(max(0.0, cursor_y - window_h / 2))
+            if cursor_x < scroll_x or cursor_x + 3 * char_width > scroll_x + window_w:
+                imgui.set_scroll_x(max(0.0, cursor_x - window_w / 2))
+            editor = replace(editor, reveal=False)
+
+        draw = imgui.get_window_draw_list()
+        color = imgui.get_color_u32
+        lo, hi = textedit.selection(editor)
+        first = max(0, int(imgui.get_scroll_y() / height) - 1)
+        position = sum(len(line) + 1 for line in lines[:first])
+        for index in range(first, min(len(lines), first + int(size[1] / height) + 3)):
+            line, y = lines[index], origin[1] + index * height
+            right = origin[0] + content_width
+            if index == row:
+                draw.add_rect_filled((origin[0], y), (right, y + height), color(CURRENT_LINE))
+            if index + 1 == error_line:
+                draw.add_rect_filled((origin[0], y), (right, y + height), color(ERROR_LINE))
+            if lo < hi and hi > position and lo <= position + len(line):
+                a = len(line[:max(0, lo - position)].expandtabs(4))
+                b = len(line[:max(0, hi - position)].expandtabs(4)) + (hi > position + len(line))
+                draw.add_rect_filled((origin[0] + gutter + a * char_width, y),
+                                     (origin[0] + gutter + b * char_width, y + height), color(SELECTION))
+            number = str(index + 1)
+            draw.add_text((origin[0] + gutter - (len(number) + 1) * char_width, y), color(COLORS["comment"]), number)
+            prefix = ""
+            for text, kind in spans[index]:
+                before = len(prefix.expandtabs(4))
+                prefix += text
+                draw.add_text((origin[0] + gutter + before * char_width, y), color(COLORS[kind]),
+                              prefix.expandtabs(4)[before:])
+            position += len(line) + 1
+        if focused and imgui.get_time() % 1.1 < 0.7:  # blinking cursor
+            x, y = origin[0] + cursor_x, origin[1] + cursor_y
+            draw.add_line((x, y), (x, y + height - 2.0), color(COLORS["text"]), 1.0)
+        return editor
+    finally:
+        imgui.end_child()