janela 0.14.1 → 0.14.2

package/README.md

@@ -6,9 +6,11 @@ Desktop and mobile apps in pure TypeScript, compiled to native. No Rust, no
 Node, no Electron. The backend is TypeScript compiled to a native binary by
 [scriptc](https://scriptc.dev); the window is the OS webview via
 [webview/webview](https://github.com/webview/webview). A desktop binary comes
-out around 200–400 KB — 191 KB for the smallest template — with no bundled
+out around 225–420 KB — 225 KB for the smallest template — with no bundled
 browser and no bundled runtime; iOS and Android bundles land around
-211–415 KB. Per-template figures are in
+228–421 KB. Those are the *starter's* figures, and about 35 KB of each is the
+native file dialog and worker-thread reader it demonstrates: delete the "Files
+and the window" card and its two commands and the smallest binary is 212 KB. Per-template figures are in
 [docs/frontend.md](../../docs/frontend.md).
 
 Five targets, one runtime — the same `main.ts`, the same typed contract and the
@@ -30,6 +32,7 @@ desktop-only for now; on mobile they report clearly when called.
 
 ```bash
 npm install -g janela     # or: npx janela init my-app
+janela --version          # which janela you actually have
 janela init my-app        # (or `jn init my-app`)
 cd my-app
 janela dev                # build + run with logs in the terminal
@@ -44,6 +47,11 @@ cd my-app && npm install
 janela dev                            # Vite dev server + HMR, in a native window
 ```
 
+A `--template` a globally installed CLI has never heard of is now an error
+rather than a silent fallback, and `janela --version` says which one you are
+running — worth checking first if a scaffolded project comes out looking
+nothing like the screenshots.
+
 `vanilla` is the default and needs no frontend toolchain at all. With a
 framework, `janela dev` runs your Vite dev server and points the window at it,
 and `janela build` flattens the production bundle into the binary.

package/api/index.d.ts

@@ -94,10 +94,20 @@ export interface JanelaClient<A> {
   /**
    * Call a declared command. Unknown names and wrong argument shapes are
    * compile errors, and the result type comes from the contract.
+   *
+   * A command declared to take nothing — `quit: () => void` — normalises to
+   * `args: null`, and for those the argument is omitted rather than passed as
+   * an explicit `null`. That is what the rest-tuple is for: it makes the
+   * parameter optional for exactly those commands, and required with the
+   * declared shape for every other one. The bracketed `[X] extends [null]`
+   * form is deliberate — a bare `null extends X` would also match a command
+   * whose arguments are legitimately nullable.
    */
   invoke<K extends keyof CommandsOf<A> & string>(
     name: K,
-    args: CommandsOf<A>[K]["args"],
+    ...args: [CommandsOf<A>[K]["args"]] extends [null]
+      ? [args?: null]
+      : [args: CommandsOf<A>[K]["args"]]
   ): Promise<CommandsOf<A>[K]["result"]>;
   /**
    * Subscribe to a declared event; the payload type is inferred. Returns a

package/bin/janela.mjs

@@ -4,6 +4,7 @@
 //   janela init <name>   scaffold a new project
 //   janela build         compile the project to a native binary (+ .app on macOS)
 //   janela dev           build, then run the binary with logs in the terminal
+//   janela --version     which janela this is
 //
 // A project is: index.html (frontend), src-host/main.ts (commands),
 // janela.conf.json (window + bundle config). Everything else — the C shim over
@@ -26,6 +27,9 @@ import {
 
 const KIT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const require = createRequire(join(KIT, "package.json"));
+// createRequire is rooted AT the package.json, so "./package.json" is this
+// package's own — not the bin/ directory's and not the workspace's.
+const VERSION = require("./package.json").version;
 
 function fail(msg) {
   console.error(`janela: ${msg}`);
@@ -1277,6 +1281,16 @@ async function dev(root) {
 const argv = process.argv.slice(2);
 const cmd = argv[0];
 
+// Answered before anything else, because the question it settles is "is the
+// janela running this command the one I think it is?". A globally installed
+// CLI several minor versions behind accepts `init` and quietly ignores flags it
+// has never heard of — `--template` did not exist before 0.3.0 — so the only
+// symptom is a project that came out looking wrong.
+if (cmd === "--version" || cmd === "-v") {
+  console.log(VERSION);
+  process.exit(0);
+}
+
 function flag(name, fallback) {
   const eq = argv.find((a) => a.startsWith(`--${name}=`));
   if (eq) return eq.slice(name.length + 3);
@@ -1356,9 +1370,11 @@ switch (cmd) {
     break;
   default:
     console.log(
-      "usage: janela init <name> [--template vanilla|vue|react|svelte|solid]\n" +
+      `janela ${VERSION}\n\n` +
+        "usage: janela init <name> [--template vanilla|vue|react|svelte|solid]\n" +
         "       janela build [--target desktop|ios|android]\n" +
-        "       janela dev   [--target desktop|ios|android]",
+        "       janela dev   [--target desktop|ios|android]\n" +
+        "       janela --version",
     );
     process.exit(cmd ? 1 : 0);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "janela",
-  "version": "0.14.1",
+  "version": "0.14.2",
   "description": "Desktop, iOS and Android apps in pure TypeScript, compiled to native. No Rust, no Node, no Electron.",
   "type": "module",
   "bin": {

package/templates/index.html

@@ -1,33 +1,204 @@
 <!doctype html>
-<html>
+<html lang="en">
   <head>
     <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>__NAME__</title>
     <style>
-      body { font: 16px -apple-system, sans-serif; padding: 2rem; }
-      input[type="number"] { width: 5em; }
-      #events { color: #666; font-size: 13px; }
+      /* Everything here is yours to replace. It is deliberately one file with
+         no dependencies: this template has no bundler, so what you see is what
+         runs. The mark below is drawn in CSS rather than shipped as an image —
+         a janela frontend is embedded in the binary, so every asset has to be
+         inlined anyway, and a window needs no artwork. */
+      :root {
+        color-scheme: light dark;
+        --bg: #f6f6f7;
+        --card: #ffffff;
+        --text: #18181b;
+        --muted: #71717a;
+        --line: #e4e4e7;
+        --accent: #2563eb;
+        --accent-soft: #eff4ff;
+        --shadow: 0 1px 2px rgb(0 0 0 / 0.04), 0 8px 24px -12px rgb(0 0 0 / 0.12);
+      }
+      @media (prefers-color-scheme: dark) {
+        :root {
+          --bg: #17171a;
+          --card: #202024;
+          --text: #fafafa;
+          --muted: #a1a1aa;
+          --line: #2e2e34;
+          --accent: #60a5fa;
+          --accent-soft: #1d2433;
+          --shadow: 0 1px 2px rgb(0 0 0 / 0.3), 0 8px 24px -12px rgb(0 0 0 / 0.5);
+        }
+      }
+
+      * { box-sizing: border-box; }
+      body {
+        margin: 0;
+        min-height: 100vh;
+        display: flex;
+        justify-content: center;
+        background: var(--bg);
+        color: var(--text);
+        font: 15px/1.55 -apple-system, BlinkMacSystemFont, "Segoe UI", system-ui, sans-serif;
+        -webkit-font-smoothing: antialiased;
+      }
+      main { width: 100%; max-width: 760px; padding: 26px 22px 32px; }
+
+      /* --- header ------------------------------------------------------- */
+      header { text-align: center; margin-bottom: 20px; }
+      .mark {
+        width: 56px; height: 44px; margin: 0 auto 14px;
+        border: 2px solid var(--text); border-radius: 8px;
+        display: flex; flex-direction: column; overflow: hidden;
+      }
+      .mark .bar {
+        height: 13px; flex: none;
+        border-bottom: 2px solid var(--text);
+        display: flex; align-items: center; gap: 3px; padding: 0 4px;
+      }
+      .mark .bar i { width: 3px; height: 3px; border-radius: 50%; background: var(--text); }
+      .mark .pane { flex: 1; background: linear-gradient(135deg, var(--accent), transparent 70%); opacity: 0.85; }
+      h1 { margin: 0; font-size: 26px; letter-spacing: -0.02em; font-weight: 650; }
+      .sub { margin: 5px 0 0; color: var(--muted); font-size: 13.5px; }
+
+      /* The one line that proves the whole stack: this string was produced by
+         TypeScript compiled to machine code, and handed to the page. */
+      .greeting {
+        margin: 0 0 20px;
+        padding: 11px 16px;
+        border: 1px solid var(--line);
+        border-radius: 10px;
+        background: var(--accent-soft);
+        font: 13px/1.5 ui-monospace, SFMono-Regular, Menlo, monospace;
+        text-align: center;
+        overflow-wrap: anywhere;
+      }
+
+      /* --- cards -------------------------------------------------------- */
+      /* auto-fit rather than a fixed column count: the same page is the iOS and
+         Android frontend, where it must read as a single column. */
+      .grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(320px, 1fr)); gap: 13px; }
+      .card {
+        background: var(--card);
+        border: 1px solid var(--line);
+        border-radius: 12px;
+        padding: 15px 17px;
+        box-shadow: var(--shadow);
+      }
+      .card h2 {
+        margin: 0 0 2px;
+        font-size: 13px; font-weight: 600;
+        letter-spacing: 0.04em; text-transform: uppercase;
+        color: var(--muted);
+      }
+      .card.wide { grid-column: 1 / -1; }
+      .card p.why { margin: 0 0 11px; color: var(--muted); font-size: 12.5px; line-height: 1.45; }
+      .card h3 {
+        margin: 16px 0 6px; font-size: 11px; font-weight: 600;
+        letter-spacing: 0.04em; text-transform: uppercase; color: var(--muted);
+      }
+      .row { display: flex; flex-wrap: wrap; gap: 8px; align-items: center; }
+
+      input, button {
+        font: inherit;
+        border-radius: 8px;
+        border: 1px solid var(--line);
+        padding: 8px 12px;
+        background: var(--card);
+        color: var(--text);
+        transition: border-color 0.15s, background 0.15s;
+      }
+      input { min-width: 0; }
+      input[type="number"] { width: 5.5em; text-align: center; }
+      input.grow { flex: 1 1 12em; }
+      input:focus-visible, button:focus-visible { outline: 2px solid var(--accent); outline-offset: 1px; }
+      button { cursor: pointer; font-weight: 500; }
+      button:hover:not(:disabled) { border-color: var(--accent); color: var(--accent); }
+      button:disabled { opacity: 0.5; cursor: default; }
+      button.primary { background: var(--accent); border-color: var(--accent); color: #fff; }
+      button.primary:hover:not(:disabled) { filter: brightness(1.08); color: #fff; }
+
+      .result { margin: 12px 0 0; font: 13px/1.5 ui-monospace, SFMono-Regular, Menlo, monospace; color: var(--muted); }
+      .result.filled { color: var(--text); }
+      pre.result { white-space: pre-wrap; overflow-wrap: anywhere; max-height: 11em; overflow: auto; margin-top: 12px; }
+
+      /* A dot that keeps moving while a 2s command is pending. If it stalls,
+         the host has blocked the UI thread — which is the bug this proves is
+         absent. */
+      .pulse { width: 8px; height: 8px; border-radius: 50%; background: var(--accent); animation: pulse 1s ease-in-out infinite; }
+      @keyframes pulse { 0%, 100% { opacity: 0.25; transform: scale(0.8); } 50% { opacity: 1; transform: scale(1.15); } }
+      @media (prefers-reduced-motion: reduce) { .pulse { animation: none; opacity: 1; } }
+
+      ul.events { list-style: none; margin: 0; padding: 0; font: 13px/1.6 ui-monospace, SFMono-Regular, Menlo, monospace; }
+      ul.events li { padding: 3px 0; border-bottom: 1px dashed var(--line); }
+      ul.events li:last-child { border-bottom: 0; }
+      ul.events:empty::after { content: "nothing yet — press add"; color: var(--muted); font-family: inherit; }
+
+      footer { margin-top: 18px; display: flex; flex-wrap: wrap; gap: 10px; align-items: center; justify-content: center; color: var(--muted); font-size: 13px; }
+      footer code { background: var(--card); border: 1px solid var(--line); border-radius: 5px; padding: 1px 5px; font-size: 12px; }
+
     </style>
   </head>
   <body>
-    <h1>__NAME__</h1>
-    <p>
-      <input id="a" type="number" value="2" /> +
-      <input id="b" type="number" value="40" />
-      <button id="add">add</button>
-      <button id="wait">wait 2s (async)</button>
-      <button id="quit">Quit</button>
-    </p>
-    <p>
-      <input id="path" type="text" value="janela.conf.json" size="32" />
-      <button id="read">read file (async)</button>
-      <button id="open">pick a file…</button>
-    </p>
-    <p>
-      <input id="title" type="text" value="__NAME__ — renamed" size="24" />
-      <button id="retitle">set window title</button>
-    </p>
-    <pre id="out">booting…</pre>
-    <ul id="events"></ul>
+    <main>
+      <header>
+        <div class="mark" aria-hidden="true">
+          <div class="bar"><i></i><i></i><i></i></div>
+          <div class="pane"></div>
+        </div>
+        <h1>__NAME__</h1>
+        <p class="sub">TypeScript, compiled to a native binary. No Rust, no Node, no Electron.</p>
+      </header>
+
+      <p class="greeting" id="out">booting…</p>
+
+      <div class="grid">
+        <section class="card">
+          <h2>Typed commands</h2>
+          <p class="why">The name, the arguments and the result are all checked at compile time — no codegen, because both sides are TypeScript.</p>
+          <div class="row">
+            <input id="a" type="number" value="2" aria-label="first number" />
+            <span aria-hidden="true">+</span>
+            <input id="b" type="number" value="40" aria-label="second number" />
+            <button id="add" class="primary">add</button>
+          </div>
+          <p class="result" id="sum">—</p>
+          <h3>Events from the host</h3>
+          <ul class="events" id="events"></ul>
+        </section>
+
+        <section class="card">
+          <h2>Async without blocking</h2>
+          <p class="why">The window keeps answering while this is pending: the dot keeps moving and <strong>add</strong> still works.</p>
+          <div class="row">
+            <button id="wait">wait 2s</button>
+            <span id="spinner" hidden><span class="pulse"></span></span>
+          </div>
+          <p class="result" id="waited">—</p>
+        </section>
+
+        <section class="card wide">
+          <h2>Files and the window</h2>
+          <p class="why">Reads run on a worker thread, so a large file never freezes the window. The dialog is the real native one.</p>
+          <div class="row">
+            <input id="path" class="grow" type="text" value="janela.conf.json" aria-label="file to read" />
+            <button id="read">read</button>
+            <button id="open">pick a file…</button>
+            <input id="title" class="grow" type="text" value="__NAME__ — renamed" aria-label="window title" />
+            <button id="retitle">set title</button>
+          </div>
+          <pre class="result" id="file">—</pre>
+        </section>
+      </div>
+
+      <footer>
+        <span>Edit <code>index.html</code> for the page and <code>src-host/main.ts</code> for the commands.</span>
+        <button id="quit">Quit</button>
+      </footer>
+    </main>
 
     <script>
       // This template has no bundler, so it uses the `janela` global that the
@@ -35,56 +206,56 @@
       // `import { invoke, listen } from "janela/api"` instead — same functions,
       // but typed and resolvable by the bundler.
       window.onload = async () => {
-        const out = document.getElementById("out");
-        const events = document.getElementById("events");
+        const $ = (id) => document.getElementById(id);
+        const show = (el, text) => {
+          el.textContent = text;
+          el.classList.add("filled");
+        };
 
         janela.listen("added", (sum) => {
           const li = document.createElement("li");
-          li.textContent = "event 'added' from host: " + sum;
-          events.prepend(li);
+          li.textContent = "host emitted 'added': " + sum;
+          $("events").prepend(li);
         });
 
-        out.textContent = await janela.invoke("greet", { name: "__NAME__" });
+        // The greeting is a round trip: the string is built in compiled
+        // TypeScript and returned to the page.
+        $("out").textContent = await janela.invoke("greet", { name: "__NAME__" });
         await janela.invoke("log", "page loaded");
 
-        document.getElementById("add").onclick = async () => {
-          const a = Number(document.getElementById("a").value);
-          const b = Number(document.getElementById("b").value);
-          const sum = await janela.invoke("add", { a, b });
-          out.textContent = `add(${a}, ${b}) -> ${sum}`;
+        $("add").onclick = async () => {
+          const a = Number($("a").value);
+          const b = Number($("b").value);
+          show($("sum"), `add(${a}, ${b}) → ${await janela.invoke("add", { a, b })}`);
         };
-        // The window stays responsive while this is pending: the spinner keeps
-        // animating and "add" still works.
-        document.getElementById("wait").onclick = async (e) => {
+
+        $("wait").onclick = async (e) => {
           e.target.disabled = true;
-          out.textContent = "waiting… (try 'add' — it still answers)";
-          out.textContent = await janela.invoke("wait", { ms: 2000 });
+          $("spinner").hidden = false;
+          show($("waited"), "waiting… try add, it still answers");
+          const answer = await janela.invoke("wait", { ms: 2000 });
+          show($("waited"), answer);
+          $("spinner").hidden = true;
           e.target.disabled = false;
         };
 
-        // Reads run on a worker thread in the shim, so even a large file
-        // does not freeze the window while it loads.
-        document.getElementById("read").onclick = async () => {
-          const path = document.getElementById("path").value;
+        $("read").onclick = async () => {
+          const path = $("path").value;
           const r = await janela.invoke("readFile", { path });
-          out.textContent = r.ok
-            ? `${path}: ${r.length} chars\n\n` + r.text.slice(0, 400)
-            : "error: " + r.error;
+          show($("file"), r.ok ? `${path} — ${r.length} chars\n\n${r.text.slice(0, 400)}` : "error: " + r.error);
         };
 
         // The native open dialog. The window keeps serving other commands
         // while the user is deciding.
-        document.getElementById("open").onclick = async () => {
+        $("open").onclick = async () => {
           const r = await janela.invoke("openFile", {});
-          if (!r.ok) out.textContent = "error: " + r.error;
-          else if (r.cancelled) out.textContent = "cancelled";
-          else out.textContent = `${r.path}: ${r.length} chars\n\n` + r.text.slice(0, 400);
+          if (!r.ok) show($("file"), "error: " + r.error);
+          else if (r.cancelled) show($("file"), "cancelled");
+          else show($("file"), `${r.path} — ${r.length} chars\n\n${r.text.slice(0, 400)}`);
         };
 
-        document.getElementById("retitle").onclick = () =>
-          janela.invoke("setTitle", { title: document.getElementById("title").value });
-
-        document.getElementById("quit").onclick = () => janela.invoke("quit");
+        $("retitle").onclick = () => janela.invoke("setTitle", { title: $("title").value });
+        $("quit").onclick = () => janela.invoke("quit");
       };
     </script>
   </body>

package/templates/janela.conf.json

@@ -4,8 +4,8 @@
   "version": "0.1.0",
   "window": {
     "title": "__NAME__",
-    "width": 640,
-    "height": 420
+    "width": 820,
+    "height": 700
   },
   "ios": {
     "identifier": "dev.janela.__NAME__",

package/templates/react/files/index.html

@@ -2,6 +2,7 @@
 <html>
   <head>
     <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
     <title>__NAME__</title>
   </head>
   <body>

package/templates/react/files/janela.conf.json

@@ -4,8 +4,8 @@
   "version": "0.1.0",
   "window": {
     "title": "__NAME__",
-    "width": 640,
-    "height": 420
+    "width": 820,
+    "height": 700
   },
   "ios": {
     "identifier": "dev.janela.__NAME__",