janela 0.3.1 → 0.5.0

package/README.md

@@ -70,7 +70,7 @@ MSI.
 
 ```
 my-app/
-├── index.html          frontend — any HTML/JS; calls janela.invoke() / janela.listen()
+├── index.html          frontend — any HTML/JS/TS; calls invoke() / listen()
 ├── src-host/main.ts    backend — exports setup(app), registers commands
 └── janela.conf.json    name, bundle identifier, version, window
 ```
@@ -79,17 +79,42 @@ A Vite project adds a `vite.config.js` and a `src/` tree — that config is what
 makes janela build the frontend with Vite instead of inlining `index.html`
 directly.
 
-Frontend API (injected before page load):
+Frontend API — import it, and your editor and `tsc` know the shapes:
+
+```ts
+import { invoke, listen } from "janela/api";
+
+const sum = await invoke<number>("add", { a: 2, b: 40 }); // call a backend command
+listen<number>("added", (payload) => { ... });            // backend-fired events
+```
+
+`janela` is already a devDependency of a scaffolded project, so there is
+nothing extra to install. The generic is what the host command returns —
+values cross the boundary as values, so there is no JSON to parse.
+
+<details>
+<summary>No bundler? Use the injected global instead</summary>
+
+janela injects the same two functions as `window.janela` before every document
+loads, which is what the `vanilla` template uses — it needs no `npm install` at
+all:
 
 ```js
-const sum = await janela.invoke("add", { a: 2, b: 40 }); // call a backend command
-janela.listen("added", (payload) => { ... });            // backend-fired events
+const sum = await janela.invoke("add", { a: 2, b: 40 });
+janela.listen("added", (payload) => { ... });
 ```
 
-Backend API (`src-host/main.ts`):
+TypeScript users on this path can pull in the ambient types with
+`/// <reference types="janela/global" />`, or by adding `"janela/global"` to
+`compilerOptions.types`. With a bundler, prefer the import — it needs no
+ambient declaration.
+
+</details>
+
+Backend API (`src-host/main.ts`) — also typed, from the same package:
 
 ```ts
-import type { JanelaApp } from "./janela";
+import type { JanelaApp } from "janela/host";
 
 export function setup(app: JanelaApp): void {
   app.command("add", (args) => {              // values in, values out
@@ -101,6 +126,80 @@ export function setup(app: JanelaApp): void {
 }
 ```
 
+## The typed contract
+
+The API above works, but `invoke<number>("add", …)` is an *assertion*: nothing
+checks that the command exists, that the arguments match, or that the result
+is really a number. Rename a command and the page still compiles.
+
+Declare a contract instead, and both sides are checked against the same
+declarations — no code generation, nothing to keep in sync. This is the
+framework templates' default.
+
+```ts
+// src-host/main.ts
+import { defineCommands, defineEvents, emit, on, onAsync, type JanelaApp } from "janela/host";
+
+export const commands = defineCommands<{
+  add:   { args: { a: number; b: number }; result: number };
+  greet: { args: { name: string };         result: string };
+  wait:  { args: { ms: number };           result: string };
+}>();
+
+export const events = defineEvents<{ added: number }>();
+
+export type App = { commands: typeof commands; events: typeof events };
+
+export function setup(app: JanelaApp): void {
+  on(app, commands, "add", (args) => {      // args inferred: { a: number; b: number }
+    emit(app, events, "added", args.a + args.b);
+    return args.a + args.b;                 // return type checked against the contract
+  });
+  onAsync(app, commands, "wait", (args, resolve) => {
+    app.sleep(args.ms, () => resolve("waited " + args.ms + "ms"));
+  });
+}
+```
+
+```ts
+// src/App.tsx (or .vue, .svelte …)
+import { createClient } from "janela/api";
+import type { App } from "../src-host/main";   // type-only: erased at compile time
+
+const client = createClient<App>();
+
+const sum = await client.invoke("add", { a: 2, b: 40 });  // sum: number
+const off = client.on("added", (v) => console.log(v));    // v: number
+off();                                                     // unsubscribe
+```
+
+Now these are all compile errors:
+
+```ts
+await client.invoke("addd", { a: 1, b: 2 });   // unknown command
+await client.invoke("add", { a: 1, b: "2" });  // wrong argument type
+const s: string = await client.invoke("add", { a: 1, b: 2 });  // wrong result
+client.on("addedd", () => {});                 // unknown event
+client.on("added", (v: string) => {});         // wrong payload type
+```
+
+Two things worth knowing:
+
+- **`import type` is erased**, so no host code is bundled into the page — the
+  contract is a type edge and nothing more. (Verified: the built frontend
+  bundle contains none of the host's strings.)
+- **Types erase at runtime.** Payloads still cross as JSON and nothing
+  validates a malformed one. This is compile-time safety, like Tauri's
+  `invoke<T>()` — the difference is that here the types come from the host's
+  own declarations rather than from an assertion you write by hand, which is
+  only possible because both sides are TypeScript.
+
+Write `args: null` for a command that takes nothing — `args: undefined`
+lowers to a zero-parameter function and fails to compile.
+
+The untyped `invoke` / `listen` still work unchanged; the contract is
+additive, and the `vanilla` template still uses the global.
+
 ## Async commands
 
 A command that has to wait — or to chew through real work — should not freeze
@@ -210,11 +309,83 @@ nested modal loop would otherwise re-enter the host loop underneath a live TS
 frame; [docs/native-shell.md](../../docs/native-shell.md) has the details, the
 per-platform table, and the Windows GUI-subsystem note.
 
+## Migrating from 0.4.x
+
+Nothing breaks: `app.command`, `app.emit`, and the untyped `invoke` / `listen`
+all work exactly as before, and the `vanilla` template is unchanged.
+
+Two things are new:
+
+- `listen()` (and the injected `janela.listen`) now **return a disposer**.
+  Previously they returned nothing, so existing code is unaffected.
+- The **typed contract** — `defineCommands` / `defineEvents` on the host,
+  `createClient<App>()` on the page. The framework templates now scaffold with
+  it. See [The typed contract](#the-typed-contract).
+
+To adopt it in an existing app, declare what the host already exposes and swap
+the registrations:
+
+```ts
+// before
+app.command("add", (args) => {
+  const a = args as { a: number; b: number };
+  return a.a + a.b;
+});
+
+// after
+export const commands = defineCommands<{
+  add: { args: { a: number; b: number }; result: number };
+}>();
+export type App = { commands: typeof commands; events: typeof events };
+
+on(app, commands, "add", (args) => args.a + args.b);   // args inferred, no cast
+```
+
+then on the page, replace `invoke<number>("add", …)` with
+`client.invoke("add", …)` built from `createClient<App>()`.
+
+## Migrating from 0.3.x
+
+Nothing breaks: the injected `janela` global still works exactly as before.
+What changed is the recommendation — the frontend now has a real module, so
+editors and `tsc` can see it:
+
+```ts
+// 0.3.x — an untyped global, invisible to tsc and ESLint
+const sum = await janela.invoke("add", { a: 2, b: 40 });
+
+// 0.4.x — typed, resolvable, and generic over what the command returns
+import { invoke } from "janela/api";
+const sum = await invoke<number>("add", { a: 2, b: 40 });
+```
+
+The host side had the same problem and gets the same fix. `src-host/main.ts`
+used to import `JanelaApp` from `"./janela"` — a path that only exists inside
+`.janela/build/`, so an editor could never resolve it and the whole `app.*`
+API was untyped:
+
+```ts
+// 0.3.x — unresolved in the editor; JanelaApp was effectively `any`
+import type { JanelaApp } from "./janela";
+
+// 0.4.x — resolves against the installed package
+import type { JanelaApp } from "janela/host";
+```
+
+`janela build` rewrites that specifier to the local runtime copy while
+assembling the compile unit, so the build stays fully static and a project
+with no `node_modules` at all still compiles.
+
+The framework templates (`vue`, `react`, `svelte`, `solid`) are TypeScript now
+and scaffold with a `typecheck` script that covers `src/` and `src-host/`
+alike. `vanilla` stays plain JavaScript on the global, so it still needs no
+`npm install` before the first build.
+
 ## Migrating from 0.1.x
 
 Commands used to take and return **JSON text**; they now take and return
 **values**, with the runtime handling serialisation. The page-side API
-(`janela.invoke` / `janela.listen`) is unchanged.
+(`invoke` / `listen`) is unchanged.
 
 ```ts
 // 0.1.x

package/api/global.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Types for the injected `janela` global, for pages that use it directly
+ * rather than importing `janela/api` — a plain `<script>` with no bundler,
+ * typically. Pull them in from a TypeScript project with:
+ *
+ * ```ts
+ * /// <reference types="janela/global" />
+ * ```
+ *
+ * or by adding `"janela/global"` to `compilerOptions.types` in tsconfig.json.
+ *
+ * If you have a bundler, prefer `import { invoke, listen } from "janela/api"` —
+ * it needs no ambient declaration and is what the templates use.
+ */
+
+import type { JanelaBridge } from "./index.js";
+
+declare global {
+  /** The host bridge janela injects before the document loads. */
+  const janela: JanelaBridge;
+
+  interface Window {
+    janela: JanelaBridge;
+  }
+}
+
+export {};

package/api/index.d.ts

@@ -0,0 +1,102 @@
+/**
+ * The janela frontend API.
+ *
+ * Values cross the boundary as values — janela owns the JSON at the edge — so
+ * the generic parameter is what the host command returns, not a string to
+ * parse.
+ */
+
+import type { CommandShapes, Commands, Events } from "../runtime/types";
+
+/** Removes a subscription created by `listen` / `client.on`. */
+export type Unlisten = () => void;
+
+/** The bridge janela injects as `window.janela` before each document loads. */
+export interface JanelaBridge {
+  invoke<T = unknown>(cmd: string, args?: unknown): Promise<T>;
+  listen<T = unknown>(event: string, cb: (payload: T) => void): Unlisten;
+}
+
+/**
+ * Call a command the host registered with `app.command` / `app.commandAsync`.
+ *
+ * ```ts
+ * const sum = await invoke<number>("add", { a: 2, b: 40 });
+ * ```
+ *
+ * The generic is an assertion, not a check — prefer `createClient` when the
+ * host declares a contract, which verifies the name, the arguments and the
+ * result against the host's own types.
+ *
+ * Rejects if the command is unknown, if the handler rejected, or if the page
+ * is not running inside a janela window.
+ */
+export declare function invoke<T = unknown>(cmd: string, args?: unknown): Promise<T>;
+
+/**
+ * Subscribe to an event the host sends with `app.emit`. Returns a disposer.
+ *
+ * ```ts
+ * const off = listen<number>("added", (sum) => console.log(sum));
+ * off();
+ * ```
+ */
+export declare function listen<T = unknown>(
+  event: string,
+  cb: (payload: T) => void,
+): Unlisten;
+
+// ---------------------------------------------------------------------------
+// Typed contract
+// ---------------------------------------------------------------------------
+
+/** Anything shaped like a host contract module's exported `App` type. */
+export interface Contract {
+  commands: Commands<CommandShapes>;
+  events: Events<unknown>;
+}
+
+/** The command table declared by a contract. */
+export type CommandsOf<A> = A extends { commands: Commands<infer M> } ? M : never;
+
+/** The event table declared by a contract. */
+export type EventsOf<A> = A extends { events: Events<infer E> } ? E : never;
+
+/**
+ * A client bound to a host contract: command names, argument shapes, result
+ * types and event payloads are all checked against the host's declarations.
+ */
+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.
+   */
+  invoke<K extends keyof CommandsOf<A> & string>(
+    name: K,
+    args: CommandsOf<A>[K]["args"],
+  ): Promise<CommandsOf<A>[K]["result"]>;
+  /**
+   * Subscribe to a declared event; the payload type is inferred. Returns a
+   * disposer that removes the subscription.
+   */
+  on<K extends keyof EventsOf<A> & string>(
+    event: K,
+    cb: (payload: EventsOf<A>[K]) => void,
+  ): Unlisten;
+}
+
+/**
+ * Build a client checked against a host's contract.
+ *
+ * ```ts
+ * import type { App } from "../src-host/main";
+ * const client = createClient<App>();
+ * const sum = await client.invoke("add", { a: 2, b: 40 });   // number
+ * const off = client.on("added", (v) => console.log(v));      // v: number
+ * ```
+ *
+ * `import type` is erased, so no host code is bundled into the page — the
+ * contract is a type edge and nothing else. Payloads still cross as JSON, so
+ * this is compile-time safety; nothing is validated at runtime.
+ */
+export declare function createClient<A>(): JanelaClient<A>;

package/api/index.js

@@ -0,0 +1,64 @@
+// The janela frontend API — `import { invoke, listen } from "janela/api"`.
+//
+// janela injects a bridge as `window.janela` into every document before it
+// loads, so this module is a thin wrapper over that global rather than a
+// transport of its own. Importing it is the recommended style: bundlers
+// resolve it, editors complete it, and `tsc` checks it. The global stays
+// available unchanged for pages with no build step.
+
+function bridge() {
+  const found = typeof globalThis === "undefined" ? undefined : globalThis.janela;
+  if (!found || typeof found.invoke !== "function") {
+    throw new Error(
+      "janela: no host bridge on this page (window.janela is undefined). " +
+        "The page is not running inside a janela window — run the app with " +
+        "`janela dev`, or `janela build` and launch the binary. Opening the " +
+        "page in a browser, or serving it with plain `vite`, leaves no host " +
+        "to talk to.",
+    );
+  }
+  return found;
+}
+
+/**
+ * Call a command the host registered with `app.command` / `app.commandAsync`.
+ * Arguments and the resolved value are ordinary values; janela owns the
+ * serialisation at the boundary.
+ */
+export async function invoke(cmd, args) {
+  return bridge().invoke(cmd, args);
+}
+
+/**
+ * Subscribe to an event the host sends with `app.emit`. Returns a function
+ * that removes the subscription.
+ */
+export function listen(event, cb) {
+  const off = bridge().listen(event, cb);
+  // Hosts before 0.5.0 returned nothing from listen; keep a working disposer
+  // either way rather than handing back undefined.
+  if (typeof off === "function") return off;
+  return function unlisten() {
+    const all = globalThis.__wvListeners ? globalThis.__wvListeners[event] : undefined;
+    if (!all) return;
+    const i = all.indexOf(cb);
+    if (i >= 0) all.splice(i, 1);
+  };
+}
+
+/**
+ * A client bound to a host's declared contract. The type parameter carries the
+ * command and event tables; at runtime this is the same bridge as `invoke` and
+ * `listen`, so the contract costs nothing and validates nothing — it is
+ * checked entirely by the compiler.
+ */
+export function createClient() {
+  return {
+    invoke(name, args) {
+      return invoke(name, args);
+    },
+    on(event, cb) {
+      return listen(event, cb);
+    },
+  };
+}

package/bin/janela.mjs

@@ -481,9 +481,22 @@ function build(root, { devUrl = null, gui = true } = {}) {
 
   // Assemble the compile unit: runtime + user's commands + generated modules.
   cpSync(join(KIT, "runtime", "janela.ts"), join(buildDir, "janela.ts"));
+  cpSync(join(KIT, "runtime", "types.ts"), join(buildDir, "types.ts"));
   const mainSrc = join(root, "src-host", "main.ts");
   if (!existsSync(mainSrc)) fail("missing src-host/main.ts");
-  cpSync(mainSrc, join(buildDir, "main.ts"));
+  // A project's main.ts imports from "janela/host" so that it resolves in the
+  // editor against the installed package. Here it is compiled next to the
+  // runtime instead, so the specifier is rewritten to that local copy: the
+  // build never resolves through node_modules, which keeps it static and will
+  // keep working when "janela/host" starts exporting values (not just types)
+  // as well.
+  writeFileSync(
+    join(buildDir, "main.ts"),
+    readFileSync(mainSrc, "utf8").replace(
+      /(\bfrom\s*)(['"])janela\/host\2/g,
+      "$1$2./janela$2",
+    ),
+  );
 
   const html = frontendHtml(root, conf, devUrl);
   writeFileSync(
@@ -616,6 +629,7 @@ function init(name, template) {
     const extra = JSON.parse(readFileSync(join(tdir, "deps.json"), "utf8"));
     pkg.type = "module";
     Object.assign(pkg.devDependencies, extra.devDependencies ?? {});
+    Object.assign(pkg.scripts, extra.scripts ?? {});
     if (extra.dependencies) pkg.dependencies = extra.dependencies;
   }
 

package/package.json

@@ -1,12 +1,25 @@
 {
   "name": "janela",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "description": "Desktop apps in pure TypeScript, compiled to native. No Rust, no Node, no Electron.",
   "type": "module",
   "bin": {
     "janela": "bin/janela.mjs",
     "jn": "bin/janela.mjs"
   },
+  "exports": {
+    "./api": {
+      "types": "./api/index.d.ts",
+      "default": "./api/index.js"
+    },
+    "./host": {
+      "types": "./runtime/types.ts"
+    },
+    "./global": {
+      "types": "./api/global.d.ts"
+    },
+    "./package.json": "./package.json"
+  },
   "dependencies": {
     "scriptc": "0.0.35"
   },
@@ -33,6 +46,7 @@
     "node": ">=24"
   },
   "files": [
+    "api/",
     "bin/",
     "runtime/",
     "shim/",

package/runtime/janela.ts

@@ -67,6 +67,11 @@ const BOOTSTRAP =
   "  listen: function (event, cb) {" +
   "    if (!window.__wvListeners[event]) window.__wvListeners[event] = [];" +
   "    window.__wvListeners[event].push(cb);" +
+  "    return function () {" +
+  "      var a = window.__wvListeners[event] || [];" +
+  "      var i = a.indexOf(cb);" +
+  "      if (i >= 0) a.splice(i, 1);" +
+  "    };" +
   "  }," +
   "};" +
   "window.__wvEmit = function (event, payload) {" +
@@ -74,124 +79,39 @@ const BOOTSTRAP =
   "  for (var i = 0; i < cbs.length; i++) cbs[i](payload);" +
   "};";
 
-// Handlers take the invoked arguments as a value and return a value; the
-// runtime owns JSON at the boundary. `args` is whatever the page passed to
-// janela.invoke(name, args) — cast it to the shape you expect. The return
-// value is what the page's promise resolves with.
-//
-// Throwing is not supported by scriptc across the FFI boundary. Use
-// commandAsync's `reject` to fail a call, or return an error value.
-export type CommandHandler = (args: unknown) => unknown;
-
-/**
- * An async command: return immediately, answer later. `resolve`/`reject` take
- * a value and settle the page's `await janela.invoke(...)` promise whenever
- * they are called — from a later defer()/sleep() turn, or from another
- * command. The window stays responsive for as long as the call is pending.
- */
-export type AsyncCommandHandler = (
-  args: unknown,
-  resolve: (value: unknown) => void,
-  reject: (reason: unknown) => void,
-) => void;
-
-/**
- * Completion of an async file operation. `err` is null on success; on failure
- * it carries a Node-shaped message ("ENOENT: no such file or directory, open
- * '/x'") and `text` is empty. Errors arrive as values, never as throws —
- * scriptc cannot propagate an exception across the FFI boundary.
- */
-export type FsCallback = (err: string | null, text: string) => void;
-
-/** A named group of extensions offered in a dialog's file-type popup. */
-export interface DialogFilter {
-  name: string;
-  /** Bare extensions, no dot and no glob: ["png", "jpg"]. */
-  extensions: string[];
-}
-
-export interface OpenDialogOptions {
-  title?: string;
-  /** Directory the dialog opens in. */
-  defaultPath?: string;
-  /** Allow picking more than one entry. */
-  multiple?: boolean;
-  /** Pick directories instead of files. Not supported on Windows. */
-  directory?: boolean;
-  filters?: DialogFilter[];
-}
-
-export interface SaveDialogOptions {
-  title?: string;
-  defaultPath?: string;
-  /** Filename pre-filled in the name field. */
-  defaultName?: string;
-  filters?: DialogFilter[];
-}
-
-export interface WindowConfig {
-  title: string;
-  width: number;
-  height: number;
-}
-
-export interface JanelaApp {
-  handle: number;
-  names: string[];
-  handlers: CommandHandler[];
-  /** Register a named command, callable from the page as janela.invoke(name, args). */
-  command: (name: string, h: CommandHandler) => void;
-  /** Register a command that answers later; see AsyncCommandHandler. */
-  commandAsync: (name: string, h: AsyncCommandHandler) => void;
-  /** Run fn on the next turn of the host loop — the way to slice long work. */
-  defer: (fn: () => void) => void;
-  /** Run fn after at least ms. The host loop's timer; scriptc's setTimeout
-   *  cannot fire while the window is open (its loop is parked inside run()). */
-  sleep: (ms: number, fn: () => void) => void;
-  /**
-   * Read a file without blocking the window. The syscall runs on a shim
-   * worker thread; the callback lands on the UI thread on a later turn.
-   * Prefer this over node:fs readFileSync inside a command — that one blocks
-   * the loop, and with it the whole window.
-   */
-  readFileAsync: (path: string, cb: FsCallback) => void;
-  /** Write a file without blocking the window; cb(null) on success. */
-  writeFileAsync: (
-    path: string,
-    data: string,
-    cb: (err: string | null) => void,
-  ) => void;
-  /**
-   * Show the native "open" dialog. `cb` gets the chosen paths, or null if the
-   * user cancelled. The modal runs on a later turn of the UI thread, so
-   * calling this from inside a command does not block that command's reply —
-   * pair it with commandAsync when the page is waiting for the result.
-   */
-  openFileDialog: (
-    options: OpenDialogOptions,
-    cb: (paths: string[] | null, err?: string) => void,
-  ) => void;
-  /** Show the native "save" dialog; cb gets the path, or null on cancel. */
-  saveFileDialog: (
-    options: SaveDialogOptions,
-    cb: (path: string | null, err?: string) => void,
-  ) => void;
-  /** Change the window title at any time, not just at startup. */
-  setTitle: (title: string) => void;
-  /**
-   * Resize the window. `hint` is webview's sizing hint: 0 none, 1 minimum,
-   * 2 maximum, 3 fixed.
-   */
-  setSize: (width: number, height: number, hint?: number) => void;
-  /** Enter or leave fullscreen. */
-  setFullscreen: (on: boolean) => void;
-  /** Fire an event into the page; the payload is delivered as a value. */
-  emit: (event: string, payload: unknown) => void;
-  /** Close the window and make run() return. */
-  quit: () => void;
-  /** Show the page and block until the window closes. Returns the run status. */
-  run: (html: string) => number;
-}
+// The public host types live in ./types (shipped as `janela/host` too, so a
+// user's editor can see them). Re-exported here because the compiled build
+// resolves them through this module — see the specifier rewrite in the CLI.
+export type {
+  AsyncCommandHandler,
+  CommandHandler,
+  CommandShape,
+  CommandShapes,
+  Commands,
+  DialogFilter,
+  Events,
+  FsCallback,
+  JanelaApp,
+  OpenDialogOptions,
+  SaveDialogOptions,
+  WindowConfig,
+} from "./types";
+
+// The typed-contract helpers are values, so they are re-exported as values.
+// A project's `import { defineCommands } from "janela/host"` is rewritten to
+// this module by the CLI before scriptc sees it.
+export { defineCommands, defineEvents, emit, on, onAsync } from "./types";
+
+import type {
+  AsyncCommandHandler,
+  CommandHandler,
+  DialogFilter,
+  FsCallback,
+  JanelaApp,
+  OpenDialogOptions,
+  SaveDialogOptions,
+  WindowConfig,
+} from "./types";
 
 // JSON.stringify yields undefined for undefined; the wire always needs a
 // value, and a command that returns nothing should read as null in the page.