Skip to content

Releases

v0.1.1

Choose a tag to compare

@coldsofttech coldsofttech released this 08 Nov 14:52
ac7d8bb

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=None or --no-loading.
  • cornea.preload(). It warms up the web server libraries in the background so the first start is faster. cornea open and cornea serve use it automatically.
  • Shutdown timings are now logged at debug level.

Changed

  • Faster import. Importing Cornea Shell is about four times faster, and cornea --version and cornea doctor start 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_ready is now called after the window opens on the loading screen.

Full changelog: v0.1.0...v0.1.1

v0.1.0

Choose a tag to compare

@coldsofttech coldsofttech released this 01 Nov 12:44
144d437

Cornea Shell

CI
Release
PyPI
Python versions
Ruff
pre-commit
License

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

Other platforms are not supported yet.

Installation

pip install cornea-shell

Or with uv:

uv add cornea-shell

Two 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/folder

The 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 closed

Your 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 the proxy extra): 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 --frameless

A 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 --frameless

Cornea 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" event
window.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.dirty
window.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...

Read more