janela 0.3.1 → 0.5.0

package/templates/solid/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/solid/files/tsconfig.json

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

package/templates/svelte/deps.json

@@ -2,6 +2,11 @@
   "devDependencies": {
     "@sveltejs/vite-plugin-svelte": "^5.0.3",
     "svelte": "^5.16.0",
-    "vite": "^6.0.7"
+    "vite": "^6.0.7",
+    "svelte-check": "^4.1.4",
+    "typescript": "^5.7.3"
+  },
+  "scripts": {
+    "typecheck": "svelte-check --tsconfig ./tsconfig.json"
   }
 }

package/templates/svelte/files/index.html

@@ -6,6 +6,6 @@
   </head>
   <body>
     <div id="app"></div>
-    <script type="module" src="/src/main.js"></script>
+    <script type="module" src="/src/main.ts"></script>
   </body>
 </html>

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

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

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

@@ -0,0 +1,7 @@
+import { mount } from "svelte";
+import App from "./App.svelte";
+
+const target = document.getElementById("app");
+if (!target) throw new Error("index.html is missing #app");
+
+mount(App, { target });

package/templates/svelte/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/svelte/files/tsconfig.json

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

package/templates/vue/deps.json

@@ -1,4 +1,14 @@
 {
-  "dependencies": { "vue": "^3.5.13" },
-  "devDependencies": { "@vitejs/plugin-vue": "^5.2.1", "vite": "^6.0.7" }
+  "dependencies": {
+    "vue": "^3.5.13"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-vue": "^5.2.1",
+    "vite": "^6.0.7",
+    "typescript": "^5.7.3",
+    "vue-tsc": "^2.2.0"
+  },
+  "scripts": {
+    "typecheck": "vue-tsc --noEmit"
+  }
 }

package/templates/vue/files/index.html

@@ -6,6 +6,6 @@
   </head>
   <body>
     <div id="app"></div>
-    <script type="module" src="/src/main.js"></script>
+    <script type="module" src="/src/main.ts"></script>
   </body>
 </html>

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

@@ -1,21 +1,29 @@
-<script setup>
-import { onMounted, ref } from "vue";
+<script setup lang="ts">
+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);
 const b = ref(40);
-const sum = ref(null);
-const events = ref([]);
+const sum = ref<number | null>(null);
+const events = ref<string[]>([]);
 
-// Backend→frontend events. The payload arrives as a value, not a JSON string.
-janela.listen("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 janela.invoke("greet", { name: "__NAME__" });
+  greeting.value = await client.invoke("greet", { name: "__NAME__" });
 });
 
 async function add() {
-  sum.value = await janela.invoke("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,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/vue/files/tsconfig.json

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

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

@@ -1,38 +0,0 @@
-import { useEffect, useState } from "react";
-import "./App.css";
-
-export default function App() {
-  const [greeting, setGreeting] = useState("…");
-  const [a, setA] = useState(2);
-  const [b, setB] = useState(40);
-  const [sum, setSum] = useState(null);
-  const [events, setEvents] = useState([]);
-
-  useEffect(() => {
-    // Backend→frontend events. The payload arrives as a value.
-    janela.listen("added", (value) =>
-      setEvents((prev) => [`host emitted: ${value}`, ...prev]),
-    );
-    janela.invoke("greet", { name: "__NAME__" }).then(setGreeting);
-  }, []);
-
-  const add = async () =>
-    setSum(await janela.invoke("add", { a: Number(a), b: Number(b) }));
-
-  return (
-    <>
-      <h1>{greeting}</h1>
-      <p>
-        <input type="number" value={a} onChange={(e) => setA(e.target.value)} /> +
-        <input type="number" value={b} onChange={(e) => setB(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.jsx

@@ -1,9 +0,0 @@
-import { StrictMode } from "react";
-import { createRoot } from "react-dom/client";
-import App from "./App.jsx";
-
-createRoot(document.getElementById("root")).render(
-  <StrictMode>
-    <App />
-  </StrictMode>,
-);

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

@@ -1,35 +0,0 @@
-import { createSignal, onMount, For, Show } from "solid-js";
-import "./App.css";
-
-export default function App() {
-  const [greeting, setGreeting] = createSignal("…");
-  const [a, setA] = createSignal(2);
-  const [b, setB] = createSignal(40);
-  const [sum, setSum] = createSignal(null);
-  const [events, setEvents] = createSignal([]);
-
-  // Backend→frontend events. The payload arrives as a value.
-  janela.listen("added", (value) =>
-    setEvents((prev) => [`host emitted: ${value}`, ...prev]),
-  );
-
-  onMount(async () => setGreeting(await janela.invoke("greet", { name: "__NAME__" })));
-
-  const add = async () =>
-    setSum(await janela.invoke("add", { a: Number(a()), b: Number(b()) }));
-
-  return (
-    <>
-      <h1>{greeting()}</h1>
-      <p>
-        <input type="number" value={a()} onInput={(e) => setA(e.currentTarget.value)} /> +
-        <input type="number" value={b()} onInput={(e) => setB(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.jsx

@@ -1,4 +0,0 @@
-import { render } from "solid-js/web";
-import App from "./App.jsx";
-
-render(() => <App />, document.getElementById("root"));

package/templates/svelte/files/src/main.js

@@ -1,4 +0,0 @@
-import { mount } from "svelte";
-import App from "./App.svelte";
-
-mount(App, { target: document.getElementById("app") });