janela 0.3.1 → 0.5.0

package/runtime/types.ts

@@ -0,0 +1,251 @@
+/**
+ * Public host-side types for a janela app — the shapes `src-host/main.ts`
+ * works with.
+ *
+ * This file is the single definition of those types. It is both:
+ *   - what `import type { JanelaApp } from "janela/host"` resolves to in an
+ *     editor, via the package's exports map; and
+ *   - re-exported by runtime/janela.ts, which is what the compiled build
+ *     actually links against (the CLI copies both files into .janela/build/).
+ *
+ * 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
+// 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;
+}
+
+// ---------------------------------------------------------------------------
+// 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 {};
+}
+
+/**
+ * Register a command against the contract. `args` is inferred from the
+ * contract, and the return type is checked against it, so the handler is
+ * written once with no casts.
+ *
+ * ```ts
+ * on(app, commands, "add", (args) => args.a + args.b);
+ * ```
+ */
+export function on<M extends CommandShapes, K extends keyof M & string>(
+  app: JanelaApp,
+  _commands: Commands<M>,
+  name: K,
+  handler: (args: M[K]["args"]) => M[K]["result"],
+): void {
+  app.command(name, (args: unknown) => handler(args as M[K]["args"]));
+}
+
+/**
+ * Register a command that answers on a later turn. `resolve` takes the
+ * contract's result type; see AsyncCommandHandler for the timing rules.
+ */
+export function onAsync<M extends CommandShapes, K extends keyof M & string>(
+  app: JanelaApp,
+  _commands: Commands<M>,
+  name: K,
+  handler: (
+    args: M[K]["args"],
+    resolve: (value: M[K]["result"]) => void,
+    reject: (reason: unknown) => void,
+  ) => void,
+): void {
+  app.commandAsync(
+    name,
+    (args: unknown, resolve: (value: unknown) => void, reject: (reason: unknown) => void) => {
+      handler(
+        args as M[K]["args"],
+        (value: M[K]["result"]) => resolve(value),
+        reject,
+      );
+    },
+  );
+}
+
+/**
+ * Emit a declared event. The name must exist in the contract and the payload
+ * must match its type.
+ *
+ * ```ts
+ * emit(app, events, "added", 42);
+ * ```
+ */
+export function emit<E, K extends keyof E & string>(
+  app: JanelaApp,
+  _events: Events<E>,
+  name: K,
+  payload: E[K],
+): void {
+  app.emit(name, payload);
+}

package/templates/index.html

@@ -30,8 +30,10 @@
     <ul id="events"></ul>
 
     <script>
-      // `janela.invoke(name, args)` and `janela.listen(event, cb)` are injected by
-      // janela before the page loads — the Tauri-shaped frontend API.
+      // This template has no bundler, so it uses the `janela` global that the
+      // host injects before the page loads. Projects with a build step should
+      // `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");

package/templates/main.ts

@@ -8,7 +8,7 @@
 // complete variable initializer — wrap it in any expression (`+ 0`). Plain
 // TypeScript like everything in this file is unaffected.
 
-import type { JanelaApp } from "./janela";
+import type { JanelaApp } from "janela/host";
 
 export function setup(app: JanelaApp): void {
   app.command("add", (args) => {

package/templates/react/deps.json

@@ -1,4 +1,16 @@
 {
-  "dependencies": { "react": "^19.0.0", "react-dom": "^19.0.0" },
-  "devDependencies": { "@vitejs/plugin-react": "^4.3.4", "vite": "^6.0.7" }
+  "dependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-react": "^4.3.4",
+    "vite": "^6.0.7",
+    "@types/react": "^19.0.7",
+    "@types/react-dom": "^19.0.3",
+    "typescript": "^5.7.3"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  }
 }

package/templates/react/files/index.html

@@ -6,6 +6,6 @@
   </head>
   <body>
     <div id="root"></div>
-    <script type="module" src="/src/main.jsx"></script>
+    <script type="module" src="/src/main.tsx"></script>
   </body>
 </html>

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

@@ -0,0 +1,55 @@
+import { useEffect, 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";
+
+const client = createClient<Contract>();
+
+export default function App() {
+  const [greeting, setGreeting] = useState("…");
+  const [a, setA] = useState(2);
+  const [b, setB] = useState(40);
+  const [sum, setSum] = useState<number | null>(null);
+  const [events, setEvents] = useState<string[]>([]);
+
+  useEffect(() => {
+    // 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]),
+    );
+    client.invoke("greet", { name: "__NAME__" }).then(setGreeting);
+    return off;
+  }, []);
+
+  const add = async () =>
+    setSum(await client.invoke("add", { a, b }));
+
+  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>
+    </>
+  );
+}

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

@@ -0,0 +1,12 @@
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import App from "./App.tsx";
+
+const root = document.getElementById("root");
+if (!root) throw new Error("index.html is missing #root");
+
+createRoot(root).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+);

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

@@ -1,42 +1,68 @@
 // 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";
+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 };
+  log: { args: string; result: null };
+  wait: { args: { ms: number }; result: string };
+  quit: { args: null; result: null };
+}>();
+
+export const events = defineEvents<{
+  added: number;
+}>();
+
+/** The contract the page imports with `import type { App } from "../src-host/main"`. */
+export type App = { commands: typeof commands; events: typeof events };
 
 export function setup(app: JanelaApp): 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", …).
-    app.emit("added", sum);
+  // `args` is inferred from the contract, and the return type is checked
+  // against it — no casts, and no way to drift from what the page expects.
+  on(app, commands, "add", (args) => {
+    const sum = args.a + args.b;
+    emit(app, events, "added", sum);
     return sum;
   });
 
-  app.command("greet", (args) => {
-    const a = args as { name: string };
-    return "Hello, " + a.name + " — from the native TS binary";
+  on(app, commands, "greet", (args) => {
+    return "Hello, " + args.name + " — from the native TS binary";
   });
 
-  app.command("log", (args) => {
-    console.log("[host] page says:", args as string);
+  on(app, commands, "log", (args) => {
+    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");
+  onAsync(app, commands, "wait", (args, resolve) => {
+    app.sleep(args.ms, () => {
+      resolve("waited " + args.ms + "ms without blocking the UI");
     });
   });
 
-  app.command("quit", () => {
+  on(app, commands, "quit", (_args) => {
     app.quit();
+    return null;
   });
 }

package/templates/react/files/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": [
+      "ES2022",
+      "DOM",
+      "DOM.Iterable"
+    ],
+    "types": [],
+    "jsx": "react-jsx",
+    "strict": true,
+    "noEmit": true,
+    "allowImportingTsExtensions": true,
+    "skipLibCheck": true,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": true
+  },
+  "include": [
+    "src/**/*.ts",
+    "src/**/*.tsx",
+    "src-host/**/*.ts"
+  ]
+}

package/templates/solid/deps.json

@@ -1,4 +1,13 @@
 {
-  "dependencies": { "solid-js": "^1.9.4" },
-  "devDependencies": { "vite": "^6.0.7", "vite-plugin-solid": "^2.11.0" }
+  "dependencies": {
+    "solid-js": "^1.9.4"
+  },
+  "devDependencies": {
+    "vite": "^6.0.7",
+    "vite-plugin-solid": "^2.11.0",
+    "typescript": "^5.7.3"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  }
 }

package/templates/solid/files/index.html

@@ -6,6 +6,6 @@
   </head>
   <body>
     <div id="root"></div>
-    <script type="module" src="/src/main.jsx"></script>
+    <script type="module" src="/src/main.tsx"></script>
   </body>
 </html>

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

@@ -0,0 +1,55 @@
+import { createSignal, 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 [a, setA] = createSignal(2);
+  const [b, setB] = createSignal(40);
+  const [sum, setSum] = createSignal<number | null>(null);
+  const [events, setEvents] = createSignal<string[]>([]);
+
+  // 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]),
+  );
+
+  onMount(async () =>
+    setGreeting(await client.invoke("greet", { name: "__NAME__" })),
+  );
+
+  const add = async () =>
+    setSum(await client.invoke("add", { a: a(), b: b() }));
+
+  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>
+    </>
+  );
+}

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

@@ -0,0 +1,7 @@
+import { render } from "solid-js/web";
+import App from "./App.tsx";
+
+const root = document.getElementById("root");
+if (!root) throw new Error("index.html is missing #root");
+
+render(() => <App />, root);