janela 0.5.0 → 0.7.0

package/runtime/types.ts

@@ -73,64 +73,6 @@ 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
 // ---------------------------------------------------------------------------
@@ -143,11 +85,10 @@ export interface JanelaApp {
 // 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.
+// The contract is carried by the app's own type — `JanelaApp<Commands, Events>`
+// — so the tables below are types and nothing more. The `Commands`/`Events`
+// tokens and their `define*` constructors are the 0.5.x/0.6.x shape, kept so
+// projects written against it still compile.
 
 /** One command's argument and result types. */
 export interface CommandShape {
@@ -174,78 +115,25 @@ export interface Events<E> {
 /**
  * Declare the commands a host exposes.
  *
+ * @deprecated The contract needs no runtime token. Declare the tables as
+ * types and name the app itself:
+ *
  * ```ts
- * export const commands = defineCommands<{
- *   add: { args: { a: number; b: number }; result: number };
- * }>();
+ * export type AppCommands = { add: { args: { a: number; b: number }; result: number } };
+ * export type AppEvents = { added: number };
+ * export type App = JanelaApp<AppCommands, AppEvents>;
+ * export function setup(app: App): void { … }
  * ```
  */
 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.
+ * Declare the events a host emits: `defineEvents<{ added: number }>()`.
  *
- * ```ts
- * emit(app, events, "added", 42);
- * ```
+ * @deprecated Pass the event table to `JanelaApp` instead — see defineCommands.
  */
-export function emit<E, K extends keyof E & string>(
-  app: JanelaApp,
-  _events: Events<E>,
-  name: K,
-  payload: E[K],
-): void {
-  app.emit(name, payload);
+export function defineEvents<E>(): Events<E> {
+  return {};
 }

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

@@ -1,9 +1,10 @@
 // src-host/main.ts — your app's backend, compiled to native code by scriptc.
 //
-// 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.
+// The two tables below are the single declaration of what this app exposes,
+// and `App` names an app that carries them. 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.
 //
 // Two gotchas inherited from scriptc:
 //   - never use a bare FFI-backed call as a complete variable initializer;
@@ -12,56 +13,52 @@
 //     an `undefined` argument lowers to a zero-parameter function and fails
 //     to compile.
 
-import {
-  defineCommands,
-  defineEvents,
-  emit,
-  on,
-  onAsync,
-  type JanelaApp,
-} from "janela/host";
+import type { JanelaApp } from "janela/host";
 
-export const commands = defineCommands<{
+/** 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 };
-}>();
+};
 
-export const events = defineEvents<{
+/** Every event this app emits, and what each one carries. */
+export type AppEvents = {
   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 type App = JanelaApp<AppCommands, AppEvents>;
 
-export function setup(app: JanelaApp): void {
-  // `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) => {
+// 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: App): void {
+  app.command("add", (args) => {
     const sum = args.a + args.b;
-    emit(app, events, "added", sum);
+    app.emit("added", sum);
     return sum;
   });
 
-  on(app, commands, "greet", (args) => {
+  app.command("greet", (args) => {
     return "Hello, " + args.name + " — from the native TS binary";
   });
 
-  on(app, commands, "log", (args) => {
+  app.command("log", (args) => {
     console.log("[host] page says:", args);
     return null;
   });
 
   // An async command: answers later, without freezing the window.
-  onAsync(app, commands, "wait", (args, resolve) => {
+  app.commandAsync("wait", (args, resolve) => {
     app.sleep(args.ms, () => {
       resolve("waited " + args.ms + "ms without blocking the UI");
     });
   });
 
-  on(app, commands, "quit", (_args) => {
+  app.command("quit", (_args) => {
     app.quit();
     return null;
   });

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

@@ -1,9 +1,10 @@
 // src-host/main.ts — your app's backend, compiled to native code by scriptc.
 //
-// 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.
+// The two tables below are the single declaration of what this app exposes,
+// and `App` names an app that carries them. 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.
 //
 // Two gotchas inherited from scriptc:
 //   - never use a bare FFI-backed call as a complete variable initializer;
@@ -12,56 +13,52 @@
 //     an `undefined` argument lowers to a zero-parameter function and fails
 //     to compile.
 
-import {
-  defineCommands,
-  defineEvents,
-  emit,
-  on,
-  onAsync,
-  type JanelaApp,
-} from "janela/host";
+import type { JanelaApp } from "janela/host";
 
-export const commands = defineCommands<{
+/** 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 };
-}>();
+};
 
-export const events = defineEvents<{
+/** Every event this app emits, and what each one carries. */
+export type AppEvents = {
   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 type App = JanelaApp<AppCommands, AppEvents>;
 
-export function setup(app: JanelaApp): void {
-  // `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) => {
+// 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: App): void {
+  app.command("add", (args) => {
     const sum = args.a + args.b;
-    emit(app, events, "added", sum);
+    app.emit("added", sum);
     return sum;
   });
 
-  on(app, commands, "greet", (args) => {
+  app.command("greet", (args) => {
     return "Hello, " + args.name + " — from the native TS binary";
   });
 
-  on(app, commands, "log", (args) => {
+  app.command("log", (args) => {
     console.log("[host] page says:", args);
     return null;
   });
 
   // An async command: answers later, without freezing the window.
-  onAsync(app, commands, "wait", (args, resolve) => {
+  app.commandAsync("wait", (args, resolve) => {
     app.sleep(args.ms, () => {
       resolve("waited " + args.ms + "ms without blocking the UI");
     });
   });
 
-  on(app, commands, "quit", (_args) => {
+  app.command("quit", (_args) => {
     app.quit();
     return null;
   });

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

@@ -1,9 +1,10 @@
 // src-host/main.ts — your app's backend, compiled to native code by scriptc.
 //
-// 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.
+// The two tables below are the single declaration of what this app exposes,
+// and `App` names an app that carries them. 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.
 //
 // Two gotchas inherited from scriptc:
 //   - never use a bare FFI-backed call as a complete variable initializer;
@@ -12,56 +13,52 @@
 //     an `undefined` argument lowers to a zero-parameter function and fails
 //     to compile.
 
-import {
-  defineCommands,
-  defineEvents,
-  emit,
-  on,
-  onAsync,
-  type JanelaApp,
-} from "janela/host";
+import type { JanelaApp } from "janela/host";
 
-export const commands = defineCommands<{
+/** 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 };
-}>();
+};
 
-export const events = defineEvents<{
+/** Every event this app emits, and what each one carries. */
+export type AppEvents = {
   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 type App = JanelaApp<AppCommands, AppEvents>;
 
-export function setup(app: JanelaApp): void {
-  // `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) => {
+// 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: App): void {
+  app.command("add", (args) => {
     const sum = args.a + args.b;
-    emit(app, events, "added", sum);
+    app.emit("added", sum);
     return sum;
   });
 
-  on(app, commands, "greet", (args) => {
+  app.command("greet", (args) => {
     return "Hello, " + args.name + " — from the native TS binary";
   });
 
-  on(app, commands, "log", (args) => {
+  app.command("log", (args) => {
     console.log("[host] page says:", args);
     return null;
   });
 
   // An async command: answers later, without freezing the window.
-  onAsync(app, commands, "wait", (args, resolve) => {
+  app.commandAsync("wait", (args, resolve) => {
     app.sleep(args.ms, () => {
       resolve("waited " + args.ms + "ms without blocking the UI");
     });
   });
 
-  on(app, commands, "quit", (_args) => {
+  app.command("quit", (_args) => {
     app.quit();
     return null;
   });

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

@@ -1,9 +1,10 @@
 // src-host/main.ts — your app's backend, compiled to native code by scriptc.
 //
-// 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.
+// The two tables below are the single declaration of what this app exposes,
+// and `App` names an app that carries them. 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.
 //
 // Two gotchas inherited from scriptc:
 //   - never use a bare FFI-backed call as a complete variable initializer;
@@ -12,56 +13,52 @@
 //     an `undefined` argument lowers to a zero-parameter function and fails
 //     to compile.
 
-import {
-  defineCommands,
-  defineEvents,
-  emit,
-  on,
-  onAsync,
-  type JanelaApp,
-} from "janela/host";
+import type { JanelaApp } from "janela/host";
 
-export const commands = defineCommands<{
+/** 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 };
-}>();
+};
 
-export const events = defineEvents<{
+/** Every event this app emits, and what each one carries. */
+export type AppEvents = {
   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 type App = JanelaApp<AppCommands, AppEvents>;
 
-export function setup(app: JanelaApp): void {
-  // `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) => {
+// 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: App): void {
+  app.command("add", (args) => {
     const sum = args.a + args.b;
-    emit(app, events, "added", sum);
+    app.emit("added", sum);
     return sum;
   });
 
-  on(app, commands, "greet", (args) => {
+  app.command("greet", (args) => {
     return "Hello, " + args.name + " — from the native TS binary";
   });
 
-  on(app, commands, "log", (args) => {
+  app.command("log", (args) => {
     console.log("[host] page says:", args);
     return null;
   });
 
   // An async command: answers later, without freezing the window.
-  onAsync(app, commands, "wait", (args, resolve) => {
+  app.commandAsync("wait", (args, resolve) => {
     app.sleep(args.ms, () => {
       resolve("waited " + args.ms + "ms without blocking the UI");
     });
   });
 
-  on(app, commands, "quit", (_args) => {
+  app.command("quit", (_args) => {
     app.quit();
     return null;
   });