janela 0.14.1 → 0.14.2

package/templates/react/files/src/App.tsx

@@ -1,55 +1,172 @@
-import { useEffect, useState } from "react";
+import { useEffect, useRef, useState } from "react";
 import { createClient } from "janela/api";
-// Type-only import of the host contract: erased at compile time, so no host
-// code is bundled into the page.
-import type { App as Contract } from "../src-host/main";
-import "./App.css";
+// A type-only import of the host's contract. It is erased at compile time, so
+// no host code is bundled into the page — this is purely a type edge.
+import type { App as HostApp } from "../src-host/main";
 
-const client = createClient<Contract>();
+const client = createClient<HostApp>();
 
 export default function App() {
-  const [greeting, setGreeting] = useState("…");
+  const [greeting, setGreeting] = useState("booting…");
   const [a, setA] = useState(2);
   const [b, setB] = useState(40);
-  const [sum, setSum] = useState<number | null>(null);
+  const [sum, setSum] = useState("—");
+  const [waited, setWaited] = useState("—");
+  const [waiting, setWaiting] = useState(false);
   const [events, setEvents] = useState<string[]>([]);
+  const [path, setPath] = useState("janela.conf.json");
+  const [title, setTitle] = useState("__NAME__ — renamed");
+  const [fileOut, setFileOut] = useState("—");
+
+  // StrictMode mounts effects twice in development; the guard keeps the
+  // greeting from being fetched (and the listener registered) twice.
+  const started = useRef(false);
 
   useEffect(() => {
-    // The event name is checked against the contract, `value` is inferred,
-    // and `on` returns a disposer.
+    // The event name is checked against the contract and `value` is inferred.
+    // `on` returns a disposer.
     const off = client.on("added", (value) =>
-      setEvents((prev) => [`host emitted: ${value}`, ...prev]),
+      setEvents((prev) => [`host emitted 'added': ${value}`, ...prev]),
     );
-    client.invoke("greet", { name: "__NAME__" }).then(setGreeting);
+    if (!started.current) {
+      started.current = true;
+      client.invoke("greet", { name: "__NAME__" }).then(setGreeting);
+      client.invoke("log", "page loaded");
+    }
     return off;
   }, []);
 
-  const add = async () =>
-    setSum(await client.invoke("add", { a, b }));
+  async function add() {
+    setSum(`add(${a}, ${b}) → ${await client.invoke("add", { a, b })}`);
+  }
+
+  async function wait() {
+    setWaiting(true);
+    setWaited("waiting… try add, it still answers");
+    setWaited(await client.invoke("wait", { ms: 2000 }));
+    setWaiting(false);
+  }
+
+  async function read() {
+    const r = await client.invoke("readFile", { path });
+    setFileOut(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.
+  async function pick() {
+    const r = await client.invoke("openFile");
+    if (!r.ok) setFileOut(`error: ${r.error}`);
+    else if (r.cancelled) setFileOut("cancelled");
+    else setFileOut(`${r.path} — ${r.length} chars\n\n${r.text.slice(0, 400)}`);
+  }
 
   return (
-    <>
-      <h1>{greeting}</h1>
-      <p>
-        <input
-          type="number"
-          value={a}
-          onChange={(e) => setA(Number(e.target.value))}
-        />{" "}
-        +
-        <input
-          type="number"
-          value={b}
-          onChange={(e) => setB(Number(e.target.value))}
-        />
-        <button onClick={add}>add</button>
-        {sum !== null && <span> = {sum}</span>}
-      </p>
-      <ul>
-        {events.map((e, i) => (
-          <li key={i}>{e}</li>
-        ))}
-      </ul>
-    </>
+    <main>
+      <header>
+        <div className="mark" aria-hidden="true">
+          <div className="bar">
+            <i />
+            <i />
+            <i />
+          </div>
+          <div className="pane" />
+        </div>
+        <h1>__NAME__</h1>
+        <p className="sub">TypeScript, compiled to a native binary. No Rust, no Node, no Electron.</p>
+      </header>
+
+      <p className="greeting">{greeting}</p>
+
+      <div className="grid">
+        <section className="card">
+          <h2>Typed commands</h2>
+          <p className="why">
+            The name, the arguments and the result are all checked at compile time — no codegen,
+            because both sides are TypeScript.
+          </p>
+          <div className="row">
+            <input
+              type="number"
+              value={a}
+              aria-label="first number"
+              onChange={(e) => setA(Number(e.target.value))}
+            />
+            <span aria-hidden="true">+</span>
+            <input
+              type="number"
+              value={b}
+              aria-label="second number"
+              onChange={(e) => setB(Number(e.target.value))}
+            />
+            <button className="primary" onClick={add}>
+              add
+            </button>
+          </div>
+          <p className={sum === "—" ? "result" : "result filled"}>{sum}</p>
+          <h3>Events from the host</h3>
+          <ul className="events">
+            {events.map((e, i) => (
+              <li key={i}>{e}</li>
+            ))}
+          </ul>
+        </section>
+
+        <section className="card">
+          <h2>Async without blocking</h2>
+          <p className="why">
+            The window keeps answering while this is pending: the dot keeps moving and{" "}
+            <strong>add</strong> still works.
+          </p>
+          <div className="row">
+            <button disabled={waiting} onClick={wait}>
+              wait 2s
+            </button>
+            {waiting && (
+              <span>
+                <span className="pulse" />
+              </span>
+            )}
+          </div>
+          <p className={waited === "—" ? "result" : "result filled"}>{waited}</p>
+        </section>
+
+        <section className="card wide">
+          <h2>Files and the window</h2>
+          <p className="why">
+            Reads run on a worker thread, so a large file never freezes the window. The dialog is
+            the real native one.
+          </p>
+          <div className="row">
+            <input
+              className="grow"
+              type="text"
+              value={path}
+              aria-label="file to read"
+              onChange={(e) => setPath(e.target.value)}
+            />
+            <button onClick={read}>read</button>
+            <button onClick={pick}>pick a file…</button>
+            <input
+              className="grow"
+              type="text"
+              value={title}
+              aria-label="window title"
+              onChange={(e) => setTitle(e.target.value)}
+            />
+            <button onClick={() => client.invoke("setTitle", { title })}>set title</button>
+          </div>
+          <pre className={fileOut === "—" ? "result" : "result filled"}>{fileOut}</pre>
+        </section>
+      </div>
+
+      <footer>
+        <span>
+          Edit <code>src/App.tsx</code> for the page and <code>src-host/main.ts</code> for the
+          commands.
+        </span>
+        <button onClick={() => client.invoke("quit")}>Quit</button>
+      </footer>
+    </main>
   );
 }

package/templates/react/files/src/main.tsx

@@ -1,3 +1,4 @@
+import "./styles.css";
 import { StrictMode } from "react";
 import { createRoot } from "react-dom/client";
 import App from "./App.tsx";

package/templates/react/files/src/styles.css

@@ -0,0 +1,137 @@
+/* The janela starter's look. Shared by every template so a project scaffolded
+   with --template vue looks the same as one scaffolded without a framework.
+   All of it is yours to replace.
+
+   The window mark in App 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; }

package/templates/react/files/src-host/main.ts

@@ -17,9 +17,29 @@ export type AppCommands = {
   greet: (args: { name: string }) => string;
   log: (args: string) => void;
   wait: (args: { ms: number }) => string;
+  readFile: (args: { path: string }) => ReadResult;
+  openFile: () => PickResult;
+  setTitle: (args: { title: string }) => void;
   quit: () => void;
 };
 
+/**
+ * Results are declared as TOTAL records rather than unions of shapes: every
+ * field is always present, and `error` is null on success. A discriminated
+ * union would read better in isolation, but the page would then have to narrow
+ * before touching `text` — and the point of this template is to show the type
+ * edge working, not to teach narrowing.
+ */
+export type ReadResult = { ok: boolean; error: string | null; length: number; text: string };
+export type PickResult = {
+  ok: boolean;
+  error: string | null;
+  cancelled: boolean;
+  path: string;
+  length: number;
+  text: string;
+};
+
 /** Every event this app emits, and what each one carries. */
 export type AppEvents = {
   added: number;
@@ -54,6 +74,68 @@ export function setup(app: App): void {
     });
   });
 
+  // File I/O without freezing the window: the read happens on a worker thread
+  // in the shim. Use this instead of node:fs readFileSync, which blocks the
+  // host loop — and with it the whole UI — until the syscall returns.
+  app.commandAsync("readFile", (args, resolve) => {
+    app.readFileAsync(args.path, (err, text) => {
+      // Annotated, not inferred: a bare `null` in a returned literal infers as
+      // `null | undefined`, which does not lift into the declared
+      // `string | null` (scriptc SC2002).
+      const answer: ReadResult =
+        err !== null
+          ? { ok: false, error: err, length: 0, text: "" }
+          : { ok: true, error: null, length: text.length, text: text };
+      resolve(answer);
+    });
+  });
+
+  // The native "open" dialog, paired with the reader above — picking a file is
+  // what makes readFileAsync useful. commandAsync is the right shape here: the
+  // page's promise stays parked while the user takes as long as they like, and
+  // the window carries on serving other calls meanwhile.
+  app.commandAsync("openFile", (_args, resolve) => {
+    app.openFileDialog(
+      { title: "Pick a file", filters: [{ name: "Text", extensions: ["txt", "md"] }] },
+      (paths, err) => {
+        if (err !== undefined) {
+          const failed: PickResult = {
+            ok: false, error: err, cancelled: false, path: "", length: 0, text: "",
+          };
+          resolve(failed);
+          return;
+        }
+        if (paths === null) {
+          const cancelled: PickResult = {
+            ok: true, error: null, cancelled: true, path: "", length: 0, text: "",
+          };
+          resolve(cancelled);
+          return;
+        }
+        app.readFileAsync(paths[0], (rerr, text) => {
+          const answer: PickResult =
+            rerr !== null
+              ? { ok: false, error: rerr, cancelled: false, path: paths[0], length: 0, text: "" }
+              : {
+                  ok: true,
+                  error: null,
+                  cancelled: false,
+                  path: paths[0],
+                  length: text.length,
+                  text: text,
+                };
+          resolve(answer);
+        });
+      },
+    );
+  });
+
+  // The window is yours to change at runtime, not just at startup.
+  app.command("setTitle", (args) => {
+    app.setTitle(args.title);
+    return null;
+  });
+
   app.command("quit", (_args) => {
     app.quit();
     return null;

package/templates/solid/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/solid/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__",

package/templates/solid/files/src/App.tsx

@@ -1,55 +1,165 @@
-import { createSignal, onMount, For, Show } from "solid-js";
+import { createSignal, onCleanup, onMount, For, Show } from "solid-js";
 import { createClient } from "janela/api";
 // Type-only import of the host contract: erased at compile time, so no host
 // code is bundled into the page.
 import type { App as Contract } from "../src-host/main";
-import "./App.css";
 
 const client = createClient<Contract>();
 
 export default function App() {
-  const [greeting, setGreeting] = createSignal("…");
+  const [greeting, setGreeting] = createSignal("booting…");
   const [a, setA] = createSignal(2);
   const [b, setB] = createSignal(40);
-  const [sum, setSum] = createSignal<number | null>(null);
+  const [sum, setSum] = createSignal("—");
+  const [waited, setWaited] = createSignal("—");
+  const [waiting, setWaiting] = createSignal(false);
   const [events, setEvents] = createSignal<string[]>([]);
+  const [path, setPath] = createSignal("janela.conf.json");
+  const [title, setTitle] = createSignal("__NAME__ — renamed");
+  const [fileOut, setFileOut] = createSignal("—");
 
   // Backend→frontend events. The payload arrives as a value, and the generic
-  // says which value.
-  client.on("added", (value) =>
-    setEvents((prev) => [`host emitted: ${value}`, ...prev]),
+  // says which value. `on` returns a disposer.
+  onCleanup(
+    client.on("added", (value) => setEvents((prev) => [`host emitted 'added': ${value}`, ...prev])),
   );
 
-  onMount(async () =>
-    setGreeting(await client.invoke("greet", { name: "__NAME__" })),
-  );
+  onMount(async () => {
+    setGreeting(await client.invoke("greet", { name: "__NAME__" }));
+    await client.invoke("log", "page loaded");
+  });
+
+  async function add() {
+    const [x, y] = [a(), b()];
+    setSum(`add(${x}, ${y}) → ${await client.invoke("add", { a: x, b: y })}`);
+  }
+
+  async function wait() {
+    setWaiting(true);
+    setWaited("waiting… try add, it still answers");
+    setWaited(await client.invoke("wait", { ms: 2000 }));
+    setWaiting(false);
+  }
 
-  const add = async () =>
-    setSum(await client.invoke("add", { a: a(), b: b() }));
+  async function read() {
+    const p = path();
+    const r = await client.invoke("readFile", { path: p });
+    setFileOut(r.ok ? `${p} — ${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.
+  async function pick() {
+    const r = await client.invoke("openFile");
+    if (!r.ok) setFileOut(`error: ${r.error}`);
+    else if (r.cancelled) setFileOut("cancelled");
+    else setFileOut(`${r.path} — ${r.length} chars\n\n${r.text.slice(0, 400)}`);
+  }
 
   return (
-    <>
-      <h1>{greeting()}</h1>
-      <p>
-        <input
-          type="number"
-          value={a()}
-          onInput={(e) => setA(Number(e.currentTarget.value))}
-        />{" "}
-        +
-        <input
-          type="number"
-          value={b()}
-          onInput={(e) => setB(Number(e.currentTarget.value))}
-        />
-        <button onClick={add}>add</button>
-        <Show when={sum() !== null}>
-          <span> = {sum()}</span>
-        </Show>
-      </p>
-      <ul>
-        <For each={events()}>{(e) => <li>{e}</li>}</For>
-      </ul>
-    </>
+    <main>
+      <header>
+        <div class="mark" aria-hidden="true">
+          <div class="bar">
+            <i />
+            <i />
+            <i />
+          </div>
+          <div class="pane" />
+        </div>
+        <h1>__NAME__</h1>
+        <p class="sub">TypeScript, compiled to a native binary. No Rust, no Node, no Electron.</p>
+      </header>
+
+      <p class="greeting">{greeting()}</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
+              type="number"
+              value={a()}
+              aria-label="first number"
+              onInput={(e) => setA(Number(e.currentTarget.value))}
+            />
+            <span aria-hidden="true">+</span>
+            <input
+              type="number"
+              value={b()}
+              aria-label="second number"
+              onInput={(e) => setB(Number(e.currentTarget.value))}
+            />
+            <button class="primary" onClick={add}>
+              add
+            </button>
+          </div>
+          <p class={sum() === "—" ? "result" : "result filled"}>{sum()}</p>
+          <h3>Events from the host</h3>
+          <ul class="events">
+            <For each={events()}>{(e) => <li>{e}</li>}</For>
+          </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 disabled={waiting()} onClick={wait}>
+              wait 2s
+            </button>
+            <Show when={waiting()}>
+              <span>
+                <span class="pulse" />
+              </span>
+            </Show>
+          </div>
+          <p class={waited() === "—" ? "result" : "result filled"}>{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
+              class="grow"
+              type="text"
+              value={path()}
+              aria-label="file to read"
+              onInput={(e) => setPath(e.currentTarget.value)}
+            />
+            <button onClick={read}>read</button>
+            <button onClick={pick}>pick a file…</button>
+            <input
+              class="grow"
+              type="text"
+              value={title()}
+              aria-label="window title"
+              onInput={(e) => setTitle(e.currentTarget.value)}
+            />
+            <button onClick={() => client.invoke("setTitle", { title: title() })}>set title</button>
+          </div>
+          <pre class={fileOut() === "—" ? "result" : "result filled"}>{fileOut()}</pre>
+        </section>
+      </div>
+
+      <footer>
+        <span>
+          Edit <code>src/App.tsx</code> for the page and <code>src-host/main.ts</code> for the
+          commands.
+        </span>
+        <button onClick={() => client.invoke("quit")}>Quit</button>
+      </footer>
+    </main>
   );
 }

package/templates/solid/files/src/main.tsx

@@ -1,3 +1,4 @@
+import "./styles.css";
 import { render } from "solid-js/web";
 import App from "./App.tsx";