lucynui 0.1.4 → 1.0.0

package/README.md

@@ -2,9 +2,20 @@
 
 Desktop apps from plain HTML, CSS and JS. Write web files, get a native window.
 
-Built on [webview-bun](https://github.com/tr1ckydev/webview-bun) and [Elysia](https://elysiajs.com), running on Bun.
+Built on a [fork of webview-bun](https://github.com/LucyNBrowserEngine/webview-bun) and [Elysia](https://elysiajs.com), running on Bun.
 No React. No Rust. No Electron.
 
+Part of the [LucyN engine family](https://github.com/LucyNBrowserEngine/LucyNEngine).
+
+## Why this exists
+
+Electron is 200+ MB before you've written a line of code. Qt was next — building a UI in QPainter was miserable.
+So the question became: can a desktop app just be plain HTML, CSS and JS, no framework underneath? Turned out yes.
+
+The search for a lightweight window led to webview.h, the famous single-header C library. The plan was to write a
+Bun wrapper for it — then [webview-bun](https://github.com/tr1ckydev/webview-bun) turned up, already doing exactly
+that. So, like any decent open-source citizen: forked it, merged it in, and LucyN UI was born.
+
 ## Quick start
 
 Scaffold a new app and start it:
@@ -86,7 +97,8 @@ no `app.ts` in your project root.
 bin/lucyn.ts        the CLI entry point
 cli/                create-ui, init, dev, build, install hook, terminal styling
 src/                the framework
-  lucyn.ts          createApp — starts server + window
+  lucyn.ts          createApp — starts the server (in a Worker) + opens the window
+  server-worker.ts  runs the Elysia file server, off the main thread
   config.ts         reads lucyn.config.ts
   server.ts         Elysia file server + hot reload
   build.ts          compile step
@@ -106,6 +118,12 @@ webview-bun/        native window bindings + prebuilt libraries for linux, mac a
 
 Paths are resolved inside the project root only — anything escaping it gets a 403.
 
+## Architecture note
+
+`webview.run()` is a blocking native call — once the window opens, it freezes Bun's main thread until the window
+closes. If the file server ran on that same thread it would go dead the instant the window appeared, so `createApp()`
+runs the server in a `Worker` instead, keeping it responsive for the whole life of the window.
+
 ## Notes
 
 - On Windows you get a warning on startup: LucyN UI is built and tested on Linux, and Windows builds differ.
@@ -113,3 +131,11 @@ Paths are resolved inside the project root only — anything escaping it gets a
 - If `index.html` is missing, the window shows a helpful error instead of a blank page.
 - Ports: if the configured port is taken, LucyN UI keeps incrementing until it finds a free one and logs the port it
   actually used.
+
+## Note
+
+At v1.0.0 this might be done. Elysia isn't updating its API anytime soon, neither is webview, neither is Bun — me
+bolting on more APIs after that is just too much work for too little reason. I made this lib because I wanted an
+easier alternative to Qt's paint-and-draw, and it works for that. So don't come in acting like this is dead — what
+more do you want me to add?
+ Lucyn is just a new baby of me being a cpp god but just tired writing ui in cpp forgive me cpp gods i got tired good luck

package/cli/proc.ts

@@ -7,9 +7,6 @@ import * as ui from "./ui";
 /** Marks the root of a LucyN UI project. */
 export const CONFIG_FILE = "lucyn.config.ts";
 
-/** Where `create-ui` clones the starter app from. */
-export const TEMPLATE_REPO = "https://github.com/LucyNBrowserEngine/lucynui-template";
-
 /** Absolute path to the package root, wherever it is installed. */
 export function packageRoot() {
   return fileURLToPath(new URL("..", import.meta.url));
@@ -20,6 +17,11 @@ export function frameworkPath(file: string) {
   return fileURLToPath(new URL(`../src/${file}`, import.meta.url));
 }
 
+/** Absolute path to the package's own `template/` folder, wherever it is installed. */
+export function templatePath() {
+  return fileURLToPath(new URL("../template", import.meta.url));
+}
+
 export async function packageVersion() {
   const pkg = await Bun.file(new URL("../package.json", import.meta.url)).json();
   return String(pkg.version ?? "0.0.0");
@@ -91,8 +93,4 @@ export async function ensureSystemDeps() {
   ui.info("Installing system dependencies...");
   await runStep(process.cwd(), ["sudo", "apt", "install", "-y", "libgtk-4-1", "libwebkitgtk-6.0-4"], "inherit");
   ui.ok("Dependencies installed");
-}
-
-export function requireGit() {
-  if (!Bun.which("git")) throw new Error("git is required to fetch the template");
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lucynui",
-  "version": "0.1.4",
+  "version": "1.0.0",
   "description": "Desktop apps from plain HTML, CSS and JS. No React, no Rust, no Electron.",
   "license": "MIT",
   "type": "module",

package/src/lucyn.ts

@@ -1,7 +1,7 @@
 import { resolve } from "node:path";
 import { SizeHint, Webview } from "../webview-bun/src/webview";
 import { DEFAULTS, loadConfig, type LucynConfig } from "./config";
-import { errorPage, startServer, watchForChanges } from "./server";
+import { errorPage, watchForChanges } from "./server";
 
 const WINDOWS_NOTICE =
   "You are on Windows. LucyN UI on Windows is not top grade as Windows builds differ from Linux where the framework was made and tested. If you encounter any bugs or build errors please dont hesitate to open an issue at the LucyN org. Thank you.";
@@ -9,6 +9,10 @@ const WINDOWS_NOTICE =
 /**
  * Starts the file server, opens the native window and blocks until it closes.
  *
+ * The server runs in a Worker: `webview.run()` is a blocking FFI call that
+ * freezes Bun's main-thread event loop for as long as the window is open, so
+ * the server would never be able to answer requests if it lived there too.
+ *
  * Reads `lucyn.config.ts` from the project root; anything passed here wins.
  */
 export async function createApp(config: LucynConfig = {}) {
@@ -17,15 +21,22 @@ export async function createApp(config: LucynConfig = {}) {
   const root = resolve(process.cwd());
   const { title, width, height, port, dev } = { ...DEFAULTS, ...(await loadConfig(root)), ...config };
 
-  const server = await startServer(root, port);
+  const worker = new Worker(new URL("./server-worker.ts", import.meta.url).href);
+  const actualPort = await new Promise<number>((resolvePort, rejectPort) => {
+    worker.onmessage = (e: MessageEvent) => {
+      if (e.data?.ready) resolvePort(e.data.port);
+    };
+    worker.onerror = (err) => rejectPort(err);
+    worker.postMessage({ root, port });
+  });
 
-  console.log(dev ? `LucyN UI dev server running on http://localhost:${server.port}` : `LucyN UI running on http://localhost:${server.port}`);
+  console.log(dev ? `LucyN UI dev server running on http://localhost:${actualPort}` : `LucyN UI running on http://localhost:${actualPort}`);
 
   const webview = new Webview(dev, { width, height, hint: SizeHint.NONE });
   webview.title = title;
 
   if (await Bun.file(resolve(root, "index.html")).exists()) {
-    webview.navigate(`http://localhost:${server.port}`);
+    webview.navigate(`http://localhost:${actualPort}`);
   } else {
     webview.setHTML(
       errorPage(
@@ -42,9 +53,10 @@ export async function createApp(config: LucynConfig = {}) {
   webview.run();
 
   watcher?.close();
-  await server.stop();
+  worker.postMessage({ stop: true });
+  worker.terminate();
 }
 
 if (import.meta.main) {
   await createApp(process.argv.includes("--dev") ? { dev: true } : {});
-}
+}

package/src/server-worker.ts

@@ -0,0 +1,15 @@
+import { startServer } from "./server";
+
+declare const self: Worker;
+
+self.onmessage = async (e: MessageEvent) => {
+  const { root, port } = e.data as { root: string; port: number };
+  const server = await startServer(root, port);
+  self.postMessage({ ready: true, port: server.port });
+
+  self.onmessage = (stop: MessageEvent) => {
+    if (stop.data?.stop) {
+      server.stop().then(() => process.exit(0));
+    }
+  };
+};

package/template/app.ts

@@ -1,4 +1,4 @@
-import { createApp } from "lucynui";
+import { createApp } from "../src/index.ts";
 
 // Entry point for `lucyn dev` and `lucyn build`.
 createApp();

package/template/index.html

@@ -14,7 +14,12 @@
         Edit <code>index.html</code>, <code>style.css</code> or <code>app.js</code> and the window reloads by itself.
       </p>
       <button id="ping">Say hello</button>
+
+      <nav class="links">
+        <a href="/pages/about.html">About</a>
+        <a href="/pages/docs.html">Docs</a>
+      </nav>
     </main>
     <script src="/app.js"></script>
   </body>
-</html>
+</html>

package/template/package.json

@@ -7,7 +7,7 @@
     "build": "lucyn build"
   },
   "dependencies": {
-    "lucynui": "^0.1.0"
+    "lucynui": "link:.."
   },
   "trustedDependencies": ["lucynui"],
   "devDependencies": {

package/template/pages/about.html

@@ -0,0 +1,39 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>About — LucyN UI</title>
+    <link rel="stylesheet" href="/style.css" />
+  </head>
+  <body>
+    <main class="app">
+      <p class="brand">LucyN UI</p>
+      <h1>Why this exists</h1>
+
+      <p>
+        LucyN UI is part of the LucyN engine family. It was mainly made because I didn't like
+        Electron being big, and also hated how hard Qt made UI to build.
+      </p>
+      <p>
+        So I asked myself: is it possible to build a desktop app in plain, simple HTML, CSS and JS?
+        Turned out it is. I came across the likes of
+        <a href="https://tauri.app">Tauri</a> and
+        <a href="https://www.electronjs.org">Electron</a>, but learning they were 200+ MB for a
+        start, I stopped there.
+      </p>
+      <p>
+        Then I found a webview library — the infamous single <code>webview.h</code> file. I
+        thought about writing a Bun wrapper for it myself, then discovered
+        <a href="https://github.com/tr1ckydev/webview-bun">webview-bun</a>, which had already
+        written that exact wrapper.
+      </p>
+      <p>
+        So what did I do? Like a noble citizen of open source: forked it, merged it in. And well,
+        here we are — <strong>LucyN UI</strong>.
+      </p>
+
+      <button id="back" onclick="window.location.href='/index.html'">Back home</button>
+    </main>
+  </body>
+</html>

package/template/pages/docs.html

@@ -0,0 +1,57 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Docs — LucyN UI</title>
+    <link rel="stylesheet" href="/style.css" />
+  </head>
+  <body>
+    <main class="app">
+      <p class="brand">LucyN UI</p>
+      <h1>Docs</h1>
+
+      <p>Your app is just files plus a dependency on <code>lucynui</code>:</p>
+      <p>
+        <code>app.ts</code> — entry point, calls <code>createApp()</code><br />
+        <code>index.html</code> — your UI<br />
+        <code>style.css</code><br />
+        <code>app.js</code><br />
+        <code>lucyn.config.ts</code> — title / size / port
+      </p>
+
+      <h1>Commands</h1>
+      <p>
+        <code>bun run app.ts</code> — start the app<br />
+        <code>lucyn dev</code> — dev server + window, hot reload on html/css/js changes<br />
+        <code>lucyn build</code> — single binary in <code>./dist</code>
+      </p>
+
+      <h1>Config</h1>
+      <p>
+        <code>lucyn.config.ts</code> in your project root, every field optional:
+        <code>title</code>, <code>width</code>, <code>height</code>, <code>port</code>,
+        <code>dev</code>.
+      </p>
+
+      <h1>API Reference</h1>
+      <p>
+        I mean — do you know HTML? Yes. Do you know CSS? Yes. Do you know JS? Yes. Then what the
+        hell are you doing here, just go edit the template.
+      </p>
+      <p>
+        From <code>&lt;createdappfolder&gt;/app.ts</code>, you've got two ways to run it:
+      </p>
+      <p>
+        <code>bun run app.ts</code> or <code>lucynui dev</code> — start the app<br />
+        <code>bun run build</code> or <code>lucynui build</code> — ship a binary
+      </p>
+      <p>That's the whole API. You already know the rest.</p>
+
+      <nav class="links">
+        <a href="/index.html">Back home</a>
+        <a href="/pages/about.html">About</a>
+      </nav>
+    </main>
+  </body>
+</html>