Repository navigation
Releases
v0.1.1
Cornea Shell 0.1.1
A faster start-up release: the window opens right away, and the app closes promptly when you close it.
Added
- Loading screen. The window now opens straight away on a loading screen with your icon, title and a tag line, then moves to your app once it is ready. Change it or turn it off with
Loading,loading=Noneor--no-loading. cornea.preload(). It warms up the web server libraries in the background so the first start is faster.cornea openandcornea serveuse it automatically.- Shutdown timings are now logged at debug level.
Changed
- Faster import. Importing Cornea Shell is about four times faster, and
cornea --versionandcornea doctorstart quicker. The web server libraries now load when the server first starts. - Prompt exit. The app now exits right after the window closes, instead of waiting up to 10 seconds.
- The dev server command now stops together with the app.
- With a window,
on_readyis now called after the window opens on the loading screen.
Full changelog: v0.1.0...v0.1.1
v0.1.0
Cornea Shell
Show a web UI in a native Windows window, backed by a secured local server. You bring the UI, whether it is plain HTML, a React build, a Flask or Django site, or a page from a Node server. Cornea handles the window, the local security and the bridge to native features.
Why Cornea Shell?
Putting a web UI on the desktop usually means bundling a whole browser, or opening a local server that every program and web page on the machine can talk to. Cornea Shell takes a smaller path: your page runs in the Windows WebView2 window that is already installed, and it is served by a local server that only that window can use.
You keep the UI you already have, and Cornea Shell adds the parts around it: the window, the security and a short, switched-off-by-default list of native features.
What you get
- A native window on the Microsoft Edge WebView2 engine, with an optional frameless mode so your page draws its own title bar.
- A secured local server. Only your window can use it: other programs and web pages on the same machine are kept out.
- Any web UI. A folder of built files, a Python web app, or an address you already run.
- Your own Python routes next to the UI, called with ordinary
fetch(). - Your dev server, started for you. Cornea runs
npm run dev(or any command), shows it, and stops it when the window closes. - Native actions your page can call: choose a folder or file, choose where to save, open a link in the browser, read platform info, and your own.
- Opt-in native features: Windows notifications, opening files, dropped files and downloads. Each one stays off until you allow it.
- A command line and a Python API that do the same things.
Requirements
- Windows 10 or 11 with the Microsoft Edge WebView2 runtime (most up-to-date Windows installs already have it)
- Python 3.11 or newer
Other platforms are not supported yet.
Installation
pip install cornea-shellOr with uv:
uv add cornea-shellTwo optional extras: pip install "cornea-shell[wsgi]" to run Flask or Django apps (WSGI), and pip install "cornea-shell[proxy]" to serve a page from another server through Cornea (see below).
Quick start
Show a folder of web files in a window:
cornea open path/to/your/web/folderThe folder needs an index.html. For a React, Vue, Svelte or similar project, give Cornea the folder your build produces (often dist).
From Python, with your own routes and a native action:
from fastapi import APIRouter
from cornea import Shell, Static, Window
router = APIRouter()
@router.get("/greeting")
def greeting(name: str = "world") -> dict[str, str]:
return {"message": f"Hello, {name}!"}
shell = Shell(Static("web/dist"), routers=[router], window=Window(title="My App"))
@shell.action("shout")
def shout(text: str) -> str:
return text.upper()
shell.run() # opens the window and returns when it is closedYour page reaches the route at /api/greeting and the action with POST /api/bridge/shout. Both are plain fetch() calls to the same address the page came from.
Choosing what to show
| You have | Give Cornea |
|---|---|
| Plain HTML, CSS and JavaScript | the folder: cornea open web |
| A React, Vue, Svelte, Angular or similar project | the build folder: cornea open dist |
| A dev server that is already running (Vite, Next.js, Node) | the address: cornea open http://localhost:5173 --mode proxy --csp-profile dev |
| A dev server you want Cornea to start | the command and its address: cornea open --run "npm run dev" --url http://localhost:5173 --mode proxy --csp-profile dev --frameless |
| A FastAPI or Django (ASGI) app | cornea open --asgi myproject.asgi:application --app-dir . |
| A Flask or Django (WSGI) app | cornea open --wsgi myapp:app --app-dir . |
Each of these is a small, runnable project in examples.
A page from a server you already run
There are two ways to show an address such as a Vite dev server:
- Direct (the default): the window opens the address as it is. Cornea does not serve it, so it is not behind Cornea's security, it needs the normal window frame, and the page cannot use the window controls.
- Proxy (
--mode proxy, needs theproxyextra): Cornea fetches the pages and serves them from its own address. The page gets Cornea's security, the window controls and the frameless window, and hot reload keeps working.
Dev servers inject inline scripts and styles, which Cornea's strict content security policy blocks. For development, add --csp-profile dev, which allows exactly that and nothing else. Never use it for something you ship.
npm run dev # in your project; Vite listens on http://localhost:5173
cornea open http://localhost:5173 --mode proxy --csp-profile dev --framelessA dev server that Cornea starts
Instead of starting the dev server in another terminal, let Cornea do it. Give it the command with --run and the address the server listens on with --url:
cornea open --run "npm run dev" --url http://localhost:5173 --mode proxy --csp-profile dev --framelessCornea waits until the address answers, then shows it. When the window closes, Cornea stops the command and everything it started, and it does the same if Cornea itself crashes. If the command stops early, never answers (30 seconds by default, change it with --run-timeout), or the address is already in use, Cornea tells you in one short message. Use --run-cwd to run the command in another folder.
A frameless window with your own title bar
Run with --frameless and draw the title bar in your page. The buttons call Cornea:
await fetch("/api/window/minimize", { method: "POST" });
await fetch("/api/window/maximize", { method: "POST" });
await fetch("/api/window/close", { method: "POST" });Give the empty part of your bar the class pywebview-drag-region so it drags the window. GET /api/window tells your page whether the window is frameless, so it can draw the bar only when needed.
If a page comes straight from an address (the direct way) and you still want a frameless window, add --js-api. Cornea then gives the page the window controls and the native actions itself. Every page the window loads gets those powers, so use --js-api only for pages you trust. The proxy way needs no --js-api.
Talking to your page, and keeping the window open
Your Python code can tell the page that something happened. The page hears it as an ordinary event on window, named with the prefix cornea::
shell.notify("export-done", {"rows": 3}) # the page gets a "cornea:export-done" eventwindow.addEventListener("cornea:export-done", (event) => console.log(event.detail.rows));Don't lose unsaved work. Mark the window as busy and closing it is held back, whether the person uses the close button, Alt+F4 or the taskbar. The page then gets a cornea:close-blocked event so it can ask:
@shell.close_guard
def has_unsaved_work() -> bool:
return editor.dirtywindow.addEventListener("cornea:close-blocked", () => {
if (confirm("Close without saving?")) {
fetch("/api/window/close", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ force: true }),
});
}
});A page can also switch the hold on and off itself, which works from the command line too: POST /api/window/close-guard with {"enabled": true}.
Dropped files are off by default, because a full path says where a person keeps things. Turn them on with --drop-files (or Window(drop_files=True)) and the page gets a cornea:drop event whose detail.paths lists the full paths.
Opening files is off by default too. With --open-files (or Bridge(open_files=True)) the page can call the open_file action, which opens a document in the program Windows has for it, and reveal, which shows a file or folder in Explorer. Programs, scripts and shortcuts (.exe, .bat, .ps1, .lnk and similar), network paths and missing files are refused.
Windows notifications
Windows can show a notification (a toast) with a title and a message, even while your window is minimized. Windows draws and places it, so its look is Windows' own. It needs the optional extra:
pip install "cornea-shell[notifications]"Your Python code can always show one:
shell.show_notification("Export finished", "3 files were saved.", notification_id="export-1")A page can show one only if you allow it with --notifications (or Bridge(notifications=True)), so a page ca...