lucynui 0.1.3 → 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/create.ts

@@ -1,19 +1,14 @@
-import { closeSync, openSync } from "node:fs";
 import { cp } from "node:fs/promises";
 import { basename, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import * as proc from "./proc";
 import * as ui from "./ui";
 
-/** Matches the line the framework logs once the server is listening. */
 const SERVER_READY = /dev server running on http:\/\/localhost:(\d+)/;
-
-/** Files copied from the bundled template into a new project. */
-const TEMPLATE_FILES = ["index.html", "style.css", "app.js", "app.ts", "lucyn.config.ts", "tsconfig.json", ".gitignore"];
+const TEMPLATE_FILES = ["index.html", "style.css", "app.js", "app.ts", "lucyn.config.ts", "tsconfig.json", ".gitignore", "package.json"];
 
 const bun = () => proc.findBun() ?? "bun";
 
-/** Absolute path to the bundled template directory inside this package. */
 function templateDir(): string {
   return fileURLToPath(new URL("../template", import.meta.url));
 }
@@ -28,71 +23,51 @@ export async function dev(): Promise<never> {
 export async function build(): Promise<never> {
   proc.requireProject();
   ui.info("Building your app...");
-
   const code = await proc.run(process.cwd(), [bun(), proc.frameworkPath("build.ts")]);
   if (code !== 0) process.exit(code);
-
   ui.ok("Build complete! Check ./dist");
   process.exit(0);
 }
 
-/** `lucyn create-ui <appname>` — the whole zero-to-running-app pipeline. */
+/** `lucyn create-ui <appname>` */
 export async function create(appName: string): Promise<never> {
   if (process.platform === "win32") ui.warn(ui.WINDOWS_NOTICE);
-
-  const bunPath = await proc.ensureBun();
+  await proc.ensureBun();
   await proc.ensureSystemDeps();
 
-  ui.step(1, "scaffolding the template, hang on");
+  ui.step(1, "copying template files");
   await scaffoldInto(join(process.cwd(), appName));
-  await pinFramework(appName);
-  ui.done("scaffolding complete — fetching the deps and required builds");
-
-  ui.step(2, "installing modules including lucynui");
-  await proc.runStep(appName, [bunPath, "install"]);
-  ui.done("modules installed");
+  ui.done(`app created in ./${appName}`);
 
-  ui.step(3, "testing build");
-  await testBuild(appName);
-  ui.done("build was successful");
+  ui.line();
+  ui.info(`  cd ${appName}`);
+  ui.info("  bun install");
+  ui.info("  bun run dev");
+  ui.line();
 
-  ui.step(4, "starting dev with hmr");
-  const code = await runDev(appName, (port) => {
-    ui.done(`dev is up and running on port ${port}`);
-    ui.ready(basename(appName));
-  });
-
-  process.exit(code);
+  process.exit(0);
 }
 
-/** `lucyn` / `lucyn init` — scaffold into the current folder, then run it. */
+/** `lucyn` / `lucyn init` */
 export async function init(): Promise<never> {
-  const bunPath = await proc.ensureBun();
+  await proc.ensureBun();
   await proc.ensureSystemDeps();
 
   if (await isProject(process.cwd())) {
-    ui.info("This is already a LucyN UI app — starting dev.");
-  } else {
-    ui.step(1, "scaffolding the template, hang on");
-    await scaffoldInto(process.cwd());
-    ui.done("scaffolding complete — fetching the deps and required builds");
-
-    ui.step(2, "installing modules including lucynui");
-    await proc.runStep(process.cwd(), [bunPath, "install"]);
-    ui.done("modules installed");
-
-    ui.step(3, "testing build");
-    await testBuild(process.cwd());
-    ui.done("build was successful");
+    ui.info("Already a LucyN UI app. Run: bun run dev");
+    process.exit(0);
   }
 
-  ui.step(4, "starting dev with hmr");
-  const code = await runDev(process.cwd(), (port) => {
-    ui.done(`dev is up and running on port ${port}`);
-    ui.ready(basename(process.cwd()));
-  });
+  ui.step(1, "copying template files");
+  await scaffoldInto(process.cwd());
+  ui.done("done");
 
-  process.exit(code);
+  ui.line();
+  ui.info("  bun install");
+  ui.info("  bun run dev");
+  ui.line();
+
+  process.exit(0);
 }
 
 /* ------------------------------------------------------------------- helpers */
@@ -101,20 +76,6 @@ export function isProject(dir: string) {
   return Bun.file(join(dir, proc.CONFIG_FILE)).exists();
 }
 
-/** Runs a build and throws away the binary — the point is proving it compiles. */
-export async function testBuild(dir: string) {
-  const { rm } = await import("node:fs/promises");
-  const code = await proc.run(dir, [bun(), proc.frameworkPath("build.ts")]);
-  await rm(join(dir, "dist"), { recursive: true, force: true });
-
-  if (code !== 0) throw new Error("the test build failed");
-}
-
-/**
- * Copies the bundled template files into `dir`, never overwriting existing
- * files — except `package.json`: `bun add` creates a bare manifest (no scripts)
- * before postinstall runs, so we always replace it with the full template version.
- */
 export async function scaffoldInto(dir: string) {
   const { mkdir } = await import("node:fs/promises");
   await mkdir(dir, { recursive: true });
@@ -123,35 +84,11 @@ export async function scaffoldInto(dir: string) {
 
   for (const file of TEMPLATE_FILES) {
     const target = join(dir, file);
-    if (await Bun.file(target).exists()) continue;
+    if (file !== "package.json" && await Bun.file(target).exists()) continue;
     await cp(join(source, file), target);
   }
-
-  // Always write the template package.json — the bare one bun creates before
-  // postinstall (no scripts, no name, no type) is useless and must be replaced.
-  await cp(join(source, "package.json"), join(dir, "package.json"));
 }
 
-/** Points the app at this CLI's own version, so template drift can never bite. */
-async function pinFramework(dir: string) {
-  const manifest = Bun.file(join(dir, "package.json"));
-  if (!(await manifest.exists())) return;
-
-  // Running from a checkout rather than an install? Point the app at this copy
-  // so the whole flow can be tried out before the package is published.
-  const spec = import.meta.dir.includes("node_modules")
-    ? `^${await proc.packageVersion()}`
-    : `file:${proc.packageRoot()}`;
-
-  const pkg = await manifest.json();
-  pkg.dependencies = { ...(pkg.dependencies ?? {}), lucynui: spec };
-  await Bun.write(manifest, JSON.stringify(pkg, null, 2) + "\n");
-}
-
-/**
- * Starts dev in the foreground, forwarding output, and calls `onReady` with the
- * port the server actually bound to.
- */
 async function runDev(dir: string, onReady: (port: number) => void): Promise<number> {
   const child = Bun.spawn([bun(), proc.frameworkPath("lucyn.ts"), "--dev"], {
     cwd: dir,
@@ -167,7 +104,6 @@ async function runDev(dir: string, onReady: (port: number) => void): Promise<num
   for await (const chunk of child.stdout) {
     process.stdout.write(chunk);
     if (announced) continue;
-
     seen += decoder.decode(chunk, { stream: true });
     const port = SERVER_READY.exec(seen)?.[1];
     if (port) {
@@ -178,40 +114,3 @@ async function runDev(dir: string, onReady: (port: number) => void): Promise<num
 
   return await child.exited;
 }
-
-/**
- * Starts dev detached so the caller can exit, writing output to `logPath`.
- * Returns the port, or null when the window never came up.
- */
-export async function devDetached(dir: string, logPath: string): Promise<number | null> {
-  const fd = openSync(logPath, "a");
-
-  const child = Bun.spawn([bun(), proc.frameworkPath("lucyn.ts"), "--dev"], {
-    cwd: dir,
-    stdin: "ignore",
-    stdout: fd,
-    stderr: fd,
-  });
-
-  try {
-    for (let attempt = 0; attempt < 80; attempt++) {
-      await Bun.sleep(250);
-
-      const log = await Bun.file(logPath).text();
-      const port = SERVER_READY.exec(log)?.[1];
-
-      if (port) {
-        // Give it a moment to prove it survives the window actually opening.
-        await Bun.sleep(500);
-        return child.exitCode === null ? Number(port) : null;
-      }
-
-      if (child.exitCode !== null) return null;
-    }
-
-    return null;
-  } finally {
-    child.unref();
-    closeSync(fd);
-  }
-}

package/cli/postinstall.ts

@@ -1,64 +1,26 @@
-import { existsSync } from "node:fs";
+import { cp } from "node:fs/promises";
 import { join, sep } from "node:path";
-import * as create from "./create";
-import * as ui from "./ui";
+import { fileURLToPath } from "node:url";
 
-/**
- * Runs after `bun add lucynui --trust` / `npm i lucynui`.
- *
- * When the folder is empty it scaffolds the starter app, proves the build works
- * and leaves a dev server running before the install command returns. Any folder
- * that already looks like a project is left completely alone.
- */
-export async function postinstall(): Promise<void> {
-  // Only when installed as a dependency — not while developing this package.
-  if (!import.meta.dir.includes("node_modules")) return;
-  if (process.env.LUCYN_SKIP_POSTINSTALL) return;
+if (!import.meta.dir.includes("node_modules")) process.exit(0);
+if (process.env.LUCYN_SKIP_POSTINSTALL) process.exit(0);
 
-  const dir = projectDir();
-  if (!dir) return;
+const projectDir = process.env.INIT_CWD
+  ?? process.env.npm_config_local_prefix
+  ?? (() => {
+    const i = import.meta.dir.lastIndexOf(`${sep}node_modules${sep}`);
+    return i === -1 ? null : import.meta.dir.slice(0, i);
+  })();
 
-  if (await create.isProject(dir)) return;
-  if (existsSync(join(dir, "index.html")) || existsSync(join(dir, "src"))) return;
+if (!projectDir) process.exit(0);
 
-  ui.useTerminal();
-  ui.info("LucyN UI found an empty project and is setting it up.");
-  ui.line();
+const template = fileURLToPath(new URL("../template", import.meta.url));
+const FILES = ["index.html", "style.css", "app.js", "app.ts", "lucyn.config.ts", "tsconfig.json", ".gitignore", "package.json"];
 
-  ui.step(1, "cloning the template, hang on");
-  await create.scaffoldInto(dir);
-  ui.done("cloning complete — fetching the deps and required builds");
-
-  ui.step(2, "installing modules including lucynui");
-  ui.done("modules installed");
-
-  ui.step(3, "testing build");
-  await create.testBuild(dir);
-  ui.done("build was successful");
-
-  ui.step(4, "starting dev with hmr");
-  const logPath = join(dir, ".lucyn-dev.log");
-  const port = await create.devDetached(dir, logPath);
-
-  if (port === null) {
-    ui.warn(`The window did not come up. Run lucyn dev yourself — log: ${logPath}`);
-    return;
-  }
-
-  ui.done(`dev is up and running on port ${port}`);
-  ui.line();
-  ui.line(`  ${ui.accent("Log:")} ${ui.text(logPath)}`);
-  ui.line();
-}
-
-/** The folder the user ran `bun add` in — the one holding `node_modules`. */
-function projectDir(): string | null {
-  const fromEnv = process.env.INIT_CWD ?? process.env.npm_config_local_prefix;
-  if (fromEnv) return fromEnv;
-
-  const marker = `${sep}node_modules${sep}`;
-  const index = import.meta.dir.lastIndexOf(marker);
-  return index === -1 ? null : import.meta.dir.slice(0, index);
+for (const file of FILES) {
+  const target = join(projectDir, file);
+  if (file !== "package.json" && await Bun.file(target).exists()) continue;
+  await cp(join(template, file), target);
 }
 
-if (import.meta.main) await postinstall();
+console.log("\n  LucyN UI ready.\n\n    bun install\n    bun run dev\n");

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.3",
+  "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>