janela 0.4.0 → 0.6.0

package/runtime/types.ts

@@ -8,7 +8,8 @@
  *   - re-exported by runtime/janela.ts, which is what the compiled build
  *     actually links against (the CLI copies both files into .janela/build/).
  *
- * Keep it declaration-only: no runtime code lives here.
+ * Mostly declarations; the typed-contract helpers at the bottom are the only
+ * runtime code, and they are deliberately trivial.
  */
 
 // Handlers take the invoked arguments as a value and return a value; the
@@ -72,60 +73,60 @@ export interface WindowConfig {
   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;
+// ---------------------------------------------------------------------------
+// Typed IPC contract
+// ---------------------------------------------------------------------------
+//
+// The contract is a TYPE the host declares and the frontend imports with
+// `import type`. Because both sides are TypeScript, no code generation is
+// involved and nothing can drift: the frontend checks against the host's own
+// declarations, and the import is erased, so no host code reaches the bundle.
+//
+// Payloads still cross as JSON, so these types are compile-time only. Nothing
+// validates a malformed payload at runtime.
+//
+// SHAPE NOTE: the registrars below are standalone generic FUNCTIONS taking the
+// contract as a value, rather than methods on a returned registrar object.
+// That is not a style choice — scriptc cannot dispatch a generic method
+// through an interface-typed receiver (SC1090), so `commands.on(...)` does not
+// compile in a host build, while `on(app, commands, ...)` does.
+
+/** One command's argument and result types. */
+export interface CommandShape {
+  args: unknown;
+  result: unknown;
+}
+
+/** A contract's command table: name → shape. */
+export type CommandShapes = Record<string, CommandShape>;
+
+/**
+ * A declared command contract. Carries `M` at the type level only — the value
+ * is empty, and exists so that inference has something to read at a call site.
+ */
+export interface Commands<M extends CommandShapes> {
+  __commands?: M;
+}
+
+/** A declared event contract: event name → payload type. */
+export interface Events<E> {
+  __events?: E;
+}
+
+/**
+ * Declare the commands a host exposes.
+ *
+ * ```ts
+ * export const commands = defineCommands<{
+ *   add: { args: { a: number; b: number }; result: number };
+ * }>();
+ * ```
+ */
+export function defineCommands<M extends CommandShapes>(): Commands<M> {
+  return {};
+}
+
+/** Declare the events a host emits: `defineEvents<{ added: number }>()`. */
+export function defineEvents<E>(): Events<E> {
+  return {};
 }

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

@@ -1,7 +1,12 @@
 import { useEffect, useState } from "react";
-import { invoke, listen } from "janela/api";
+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] = useState("…");
   const [a, setA] = useState(2);
@@ -10,16 +15,17 @@ export default function App() {
   const [events, setEvents] = useState<string[]>([]);
 
   useEffect(() => {
-    // Backend→frontend events. The payload arrives as a value, and the
-    // generic says which value.
-    listen<number>("added", (value) =>
+    // The event name is checked against the contract, `value` is inferred,
+    // and `on` returns a disposer.
+    const off = client.on("added", (value) =>
       setEvents((prev) => [`host emitted: ${value}`, ...prev]),
     );
-    invoke<string>("greet", { name: "__NAME__" }).then(setGreeting);
+    client.invoke("greet", { name: "__NAME__" }).then(setGreeting);
+    return off;
   }, []);
 
   const add = async () =>
-    setSum(await invoke<number>("add", { a, b }));
+    setSum(await client.invoke("add", { a, b }));
 
   return (
     <>

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

@@ -1,42 +1,67 @@
 // src-host/main.ts — your app's backend, compiled to native code by scriptc.
 //
-// Register commands here; the page calls them with `await janela.invoke(name, args)`.
-// Handlers take the arguments as a value and return a value — the runtime owns
-// JSON at the boundary, so there is no parsing or stringifying to do here.
+// The contract below is the single declaration of what this app exposes. The
+// frontend imports `App` with `import type`, so the page is checked against
+// these exact types — command names, argument shapes, results and event
+// payloads — with no code generation and nothing to keep in sync.
 //
-// Gotcha inherited from scriptc: never use a bare FFI-backed call as a
-// complete variable initializer — wrap it in any expression (`+ 0`). Plain
-// TypeScript like everything in this file is unaffected.
+// Two gotchas inherited from scriptc:
+//   - never use a bare FFI-backed call as a complete variable initializer;
+//     wrap it in any expression (`+ 0`);
+//   - write `args: null` for a command that takes nothing, not `undefined` —
+//     an `undefined` argument lowers to a zero-parameter function and fails
+//     to compile.
 
-import type { JanelaApp } from "janela/host";
+import { defineCommands, defineEvents, type JanelaApp } from "janela/host";
 
-export function setup(app: JanelaApp): void {
+/** Every command this app answers. Declared once; the page checks against it. */
+export type AppCommands = {
+  add: { args: { a: number; b: number }; result: number };
+  greet: { args: { name: string }; result: string };
+  log: { args: string; result: null };
+  wait: { args: { ms: number }; result: string };
+  quit: { args: null; result: null };
+};
+
+/** Every event this app emits, and what each one carries. */
+export type AppEvents = {
+  added: number;
+};
+
+export const commands = defineCommands<AppCommands>();
+export const events = defineEvents<AppEvents>();
+
+/** The contract the page imports with `import type { App } from "../src-host/main"`. */
+export type App = { commands: typeof commands; events: typeof events };
+
+// Typing the app with the contract is what makes `app.command` checked: the
+// name must be one of the declared ones, `args` is inferred from it, and the
+// return value has to match. Same for `app.emit`.
+export function setup(app: JanelaApp<AppCommands, AppEvents>): void {
   app.command("add", (args) => {
-    const a = args as { a: number; b: number };
-    const sum = a.a + a.b;
-    // Backend→frontend event: the page listens with janela.listen("added", …).
+    const sum = args.a + args.b;
     app.emit("added", sum);
     return sum;
   });
 
   app.command("greet", (args) => {
-    const a = args as { name: string };
-    return "Hello, " + a.name + " — from the native TS binary";
+    return "Hello, " + args.name + " — from the native TS binary";
   });
 
   app.command("log", (args) => {
-    console.log("[host] page says:", args as string);
+    console.log("[host] page says:", args);
+    return null;
   });
 
   // An async command: answers later, without freezing the window.
   app.commandAsync("wait", (args, resolve) => {
-    const a = args as { ms: number };
-    app.sleep(a.ms, () => {
-      resolve("waited " + a.ms + "ms without blocking the UI");
+    app.sleep(args.ms, () => {
+      resolve("waited " + args.ms + "ms without blocking the UI");
     });
   });
 
-  app.command("quit", () => {
+  app.command("quit", (_args) => {
     app.quit();
+    return null;
   });
 }

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

@@ -1,7 +1,12 @@
 import { createSignal, onMount, For, Show } from "solid-js";
-import { invoke, listen } from "janela/api";
+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 [a, setA] = createSignal(2);
@@ -11,16 +16,16 @@ export default function App() {
 
   // Backend→frontend events. The payload arrives as a value, and the generic
   // says which value.
-  listen<number>("added", (value) =>
+  client.on("added", (value) =>
     setEvents((prev) => [`host emitted: ${value}`, ...prev]),
   );
 
   onMount(async () =>
-    setGreeting(await invoke<string>("greet", { name: "__NAME__" })),
+    setGreeting(await client.invoke("greet", { name: "__NAME__" })),
   );
 
   const add = async () =>
-    setSum(await invoke<number>("add", { a: a(), b: b() }));
+    setSum(await client.invoke("add", { a: a(), b: b() }));
 
   return (
     <>

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

@@ -1,42 +1,67 @@
 // src-host/main.ts — your app's backend, compiled to native code by scriptc.
 //
-// Register commands here; the page calls them with `await janela.invoke(name, args)`.
-// Handlers take the arguments as a value and return a value — the runtime owns
-// JSON at the boundary, so there is no parsing or stringifying to do here.
+// The contract below is the single declaration of what this app exposes. The
+// frontend imports `App` with `import type`, so the page is checked against
+// these exact types — command names, argument shapes, results and event
+// payloads — with no code generation and nothing to keep in sync.
 //
-// Gotcha inherited from scriptc: never use a bare FFI-backed call as a
-// complete variable initializer — wrap it in any expression (`+ 0`). Plain
-// TypeScript like everything in this file is unaffected.
+// Two gotchas inherited from scriptc:
+//   - never use a bare FFI-backed call as a complete variable initializer;
+//     wrap it in any expression (`+ 0`);
+//   - write `args: null` for a command that takes nothing, not `undefined` —
+//     an `undefined` argument lowers to a zero-parameter function and fails
+//     to compile.
 
-import type { JanelaApp } from "janela/host";
+import { defineCommands, defineEvents, type JanelaApp } from "janela/host";
 
-export function setup(app: JanelaApp): void {
+/** Every command this app answers. Declared once; the page checks against it. */
+export type AppCommands = {
+  add: { args: { a: number; b: number }; result: number };
+  greet: { args: { name: string }; result: string };
+  log: { args: string; result: null };
+  wait: { args: { ms: number }; result: string };
+  quit: { args: null; result: null };
+};
+
+/** Every event this app emits, and what each one carries. */
+export type AppEvents = {
+  added: number;
+};
+
+export const commands = defineCommands<AppCommands>();
+export const events = defineEvents<AppEvents>();
+
+/** The contract the page imports with `import type { App } from "../src-host/main"`. */
+export type App = { commands: typeof commands; events: typeof events };
+
+// Typing the app with the contract is what makes `app.command` checked: the
+// name must be one of the declared ones, `args` is inferred from it, and the
+// return value has to match. Same for `app.emit`.
+export function setup(app: JanelaApp<AppCommands, AppEvents>): void {
   app.command("add", (args) => {
-    const a = args as { a: number; b: number };
-    const sum = a.a + a.b;
-    // Backend→frontend event: the page listens with janela.listen("added", …).
+    const sum = args.a + args.b;
     app.emit("added", sum);
     return sum;
   });
 
   app.command("greet", (args) => {
-    const a = args as { name: string };
-    return "Hello, " + a.name + " — from the native TS binary";
+    return "Hello, " + args.name + " — from the native TS binary";
   });
 
   app.command("log", (args) => {
-    console.log("[host] page says:", args as string);
+    console.log("[host] page says:", args);
+    return null;
   });
 
   // An async command: answers later, without freezing the window.
   app.commandAsync("wait", (args, resolve) => {
-    const a = args as { ms: number };
-    app.sleep(a.ms, () => {
-      resolve("waited " + a.ms + "ms without blocking the UI");
+    app.sleep(args.ms, () => {
+      resolve("waited " + args.ms + "ms without blocking the UI");
     });
   });
 
-  app.command("quit", () => {
+  app.command("quit", (_args) => {
     app.quit();
+    return null;
   });
 }

package/templates/svelte/files/src/App.svelte

@@ -1,5 +1,10 @@
 <script lang="ts">
-  import { invoke, listen } from "janela/api";
+  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";
+
+  const client = createClient<Contract>();
 
   let greeting = $state("…");
   let a = $state(2);
@@ -9,12 +14,12 @@
 
   // Backend→frontend events. The payload arrives as a value, and the generic
   // says which value.
-  listen<number>("added", (value) => (events = [`host emitted: ${value}`, ...events]));
+  client.on("added", (value) => (events = [`host emitted: ${value}`, ...events]));
 
-  invoke<string>("greet", { name: "__NAME__" }).then((g) => (greeting = g));
+  client.invoke("greet", { name: "__NAME__" }).then((g) => (greeting = g));
 
   async function add() {
-    sum = await invoke<number>("add", { a: Number(a), b: Number(b) });
+    sum = await client.invoke("add", { a: Number(a), b: Number(b) });
   }
 </script>
 

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

@@ -1,42 +1,67 @@
 // src-host/main.ts — your app's backend, compiled to native code by scriptc.
 //
-// Register commands here; the page calls them with `await janela.invoke(name, args)`.
-// Handlers take the arguments as a value and return a value — the runtime owns
-// JSON at the boundary, so there is no parsing or stringifying to do here.
+// The contract below is the single declaration of what this app exposes. The
+// frontend imports `App` with `import type`, so the page is checked against
+// these exact types — command names, argument shapes, results and event
+// payloads — with no code generation and nothing to keep in sync.
 //
-// Gotcha inherited from scriptc: never use a bare FFI-backed call as a
-// complete variable initializer — wrap it in any expression (`+ 0`). Plain
-// TypeScript like everything in this file is unaffected.
+// Two gotchas inherited from scriptc:
+//   - never use a bare FFI-backed call as a complete variable initializer;
+//     wrap it in any expression (`+ 0`);
+//   - write `args: null` for a command that takes nothing, not `undefined` —
+//     an `undefined` argument lowers to a zero-parameter function and fails
+//     to compile.
 
-import type { JanelaApp } from "janela/host";
+import { defineCommands, defineEvents, type JanelaApp } from "janela/host";
 
-export function setup(app: JanelaApp): void {
+/** Every command this app answers. Declared once; the page checks against it. */
+export type AppCommands = {
+  add: { args: { a: number; b: number }; result: number };
+  greet: { args: { name: string }; result: string };
+  log: { args: string; result: null };
+  wait: { args: { ms: number }; result: string };
+  quit: { args: null; result: null };
+};
+
+/** Every event this app emits, and what each one carries. */
+export type AppEvents = {
+  added: number;
+};
+
+export const commands = defineCommands<AppCommands>();
+export const events = defineEvents<AppEvents>();
+
+/** The contract the page imports with `import type { App } from "../src-host/main"`. */
+export type App = { commands: typeof commands; events: typeof events };
+
+// Typing the app with the contract is what makes `app.command` checked: the
+// name must be one of the declared ones, `args` is inferred from it, and the
+// return value has to match. Same for `app.emit`.
+export function setup(app: JanelaApp<AppCommands, AppEvents>): void {
   app.command("add", (args) => {
-    const a = args as { a: number; b: number };
-    const sum = a.a + a.b;
-    // Backend→frontend event: the page listens with janela.listen("added", …).
+    const sum = args.a + args.b;
     app.emit("added", sum);
     return sum;
   });
 
   app.command("greet", (args) => {
-    const a = args as { name: string };
-    return "Hello, " + a.name + " — from the native TS binary";
+    return "Hello, " + args.name + " — from the native TS binary";
   });
 
   app.command("log", (args) => {
-    console.log("[host] page says:", args as string);
+    console.log("[host] page says:", args);
+    return null;
   });
 
   // An async command: answers later, without freezing the window.
   app.commandAsync("wait", (args, resolve) => {
-    const a = args as { ms: number };
-    app.sleep(a.ms, () => {
-      resolve("waited " + a.ms + "ms without blocking the UI");
+    app.sleep(args.ms, () => {
+      resolve("waited " + args.ms + "ms without blocking the UI");
     });
   });
 
-  app.command("quit", () => {
+  app.command("quit", (_args) => {
     app.quit();
+    return null;
   });
 }

package/templates/vue/files/src/App.vue

@@ -1,6 +1,11 @@
 <script setup lang="ts">
-import { onMounted, ref } from "vue";
-import { invoke, listen } from "janela/api";
+import { onMounted, onUnmounted, ref } from "vue";
+import { createClient } from "janela/api";
+// 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 } from "../src-host/main";
+
+const client = createClient<App>();
 
 const greeting = ref("…");
 const a = ref(2);
@@ -8,16 +13,17 @@ const b = ref(40);
 const sum = ref<number | null>(null);
 const events = ref<string[]>([]);
 
-// Backend→frontend events. The payload arrives as a value, not a JSON string,
-// and the generic says which value.
-listen<number>("added", (value) => events.value.unshift(`host emitted: ${value}`));
+// The event name is checked against the contract and `value` is inferred.
+// `on` returns a disposer.
+const off = client.on("added", (value) => events.value.unshift(`host emitted: ${value}`));
+onUnmounted(off);
 
 onMounted(async () => {
-  greeting.value = await invoke<string>("greet", { name: "__NAME__" });
+  greeting.value = await client.invoke("greet", { name: "__NAME__" });
 });
 
 async function add() {
-  sum.value = await invoke<number>("add", { a: Number(a.value), b: Number(b.value) });
+  sum.value = await client.invoke("add", { a: Number(a.value), b: Number(b.value) });
 }
 </script>
 

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

@@ -1,42 +1,67 @@
 // src-host/main.ts — your app's backend, compiled to native code by scriptc.
 //
-// Register commands here; the page calls them with `await janela.invoke(name, args)`.
-// Handlers take the arguments as a value and return a value — the runtime owns
-// JSON at the boundary, so there is no parsing or stringifying to do here.
+// The contract below is the single declaration of what this app exposes. The
+// frontend imports `App` with `import type`, so the page is checked against
+// these exact types — command names, argument shapes, results and event
+// payloads — with no code generation and nothing to keep in sync.
 //
-// Gotcha inherited from scriptc: never use a bare FFI-backed call as a
-// complete variable initializer — wrap it in any expression (`+ 0`). Plain
-// TypeScript like everything in this file is unaffected.
+// Two gotchas inherited from scriptc:
+//   - never use a bare FFI-backed call as a complete variable initializer;
+//     wrap it in any expression (`+ 0`);
+//   - write `args: null` for a command that takes nothing, not `undefined` —
+//     an `undefined` argument lowers to a zero-parameter function and fails
+//     to compile.
 
-import type { JanelaApp } from "janela/host";
+import { defineCommands, defineEvents, type JanelaApp } from "janela/host";
 
-export function setup(app: JanelaApp): void {
+/** Every command this app answers. Declared once; the page checks against it. */
+export type AppCommands = {
+  add: { args: { a: number; b: number }; result: number };
+  greet: { args: { name: string }; result: string };
+  log: { args: string; result: null };
+  wait: { args: { ms: number }; result: string };
+  quit: { args: null; result: null };
+};
+
+/** Every event this app emits, and what each one carries. */
+export type AppEvents = {
+  added: number;
+};
+
+export const commands = defineCommands<AppCommands>();
+export const events = defineEvents<AppEvents>();
+
+/** The contract the page imports with `import type { App } from "../src-host/main"`. */
+export type App = { commands: typeof commands; events: typeof events };
+
+// Typing the app with the contract is what makes `app.command` checked: the
+// name must be one of the declared ones, `args` is inferred from it, and the
+// return value has to match. Same for `app.emit`.
+export function setup(app: JanelaApp<AppCommands, AppEvents>): void {
   app.command("add", (args) => {
-    const a = args as { a: number; b: number };
-    const sum = a.a + a.b;
-    // Backend→frontend event: the page listens with janela.listen("added", …).
+    const sum = args.a + args.b;
     app.emit("added", sum);
     return sum;
   });
 
   app.command("greet", (args) => {
-    const a = args as { name: string };
-    return "Hello, " + a.name + " — from the native TS binary";
+    return "Hello, " + args.name + " — from the native TS binary";
   });
 
   app.command("log", (args) => {
-    console.log("[host] page says:", args as string);
+    console.log("[host] page says:", args);
+    return null;
   });
 
   // An async command: answers later, without freezing the window.
   app.commandAsync("wait", (args, resolve) => {
-    const a = args as { ms: number };
-    app.sleep(a.ms, () => {
-      resolve("waited " + a.ms + "ms without blocking the UI");
+    app.sleep(args.ms, () => {
+      resolve("waited " + args.ms + "ms without blocking the UI");
     });
   });
 
-  app.command("quit", () => {
+  app.command("quit", (_args) => {
     app.quit();
+    return null;
   });
 }