janela 0.3.0 → 0.4.0

package/runtime/types.ts

@@ -0,0 +1,131 @@
+/**
+ * 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/).
+ *
+ * Keep it declaration-only: no runtime code lives here.
+ */
+
+// 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;
+}

package/shim/wvshim.cc

@@ -820,18 +820,65 @@ int32_t wv_job_status(int32_t h, int32_t id) {
   return j->status.load(std::memory_order_acquire);
 }
 
-// Hand a finished job's payload to TS in one call. The callback is
-// lifetime:"call", so it runs synchronously here — on the UI thread, the only
-// thread allowed to touch the scriptc runtime. The worker is already done by
-// then (the caller has observed a terminal status), so `data` is stable.
-int32_t wv_job_take(int32_t h, int32_t id,
-                   void (*sink)(const uint8_t *, size_t, void *), void *ctx) {
+// Payload size in bytes, so TS knows when it has drained the whole thing.
+// f64 rather than i32: a payload may exceed 2 GB, and every scriptc number is
+// a double anyway (exact for byte counts far beyond any plausible file).
+double wv_job_size(int32_t h, int32_t id) {
+  if (!app_at(h)) return -1;
+  Job *j = job_at(id);
+  if (!j) return -1;
+  if (j->status.load(std::memory_order_acquire) == JOB_PENDING) return -1;
+  return static_cast<double>(j->data.size());
+}
+
+// Hand ONE SLICE of a finished job's payload to TS, and answer how many bytes
+// it covered. The callback is lifetime:"call", so it runs synchronously here —
+// on the UI thread, the only thread allowed to touch the scriptc runtime. The
+// worker is already done by then (the caller has observed a terminal status),
+// so `data` is stable for the whole drain.
+//
+// Slicing exists so the UI thread can decode a large payload across several
+// turns instead of stalling on all of it at once; the caller advances `offset`
+// by the returned count until it reaches wv_job_size().
+//
+// The slice end is pulled back to a UTF-8 sequence boundary, because scriptc
+// decodes a `string` param as UTF-8: cutting mid-sequence would turn one
+// character into replacement characters on both sides of the seam. Bytes that
+// are not valid UTF-8 have no boundary to find, so after four steps the cut
+// stands as asked and the payload is passed through unchanged.
+double wv_job_take_at(int32_t h, int32_t id, double offset, double max_bytes,
+                      void (*sink)(const uint8_t *, size_t, void *),
+                      void *ctx) {
   if (!app_at(h)) return -1;
   Job *j = job_at(id);
   if (!j || !sink) return -1;
   if (j->status.load(std::memory_order_acquire) == JOB_PENDING) return -1;
-  sink(reinterpret_cast<const uint8_t *>(j->data.data()), j->data.size(), ctx);
-  return 0;
+  if (offset < 0 || max_bytes < 0) return -1;
+
+  const size_t size = j->data.size();
+  const size_t off = static_cast<size_t>(offset);
+  if (off > size) return -1;
+  if (off == size) return 0;
+
+  size_t want = static_cast<size_t>(max_bytes);
+  if (want == 0) return 0;
+  size_t end = off + want;
+  if (end >= size) {
+    end = size;
+  } else {
+    const unsigned char *d =
+        reinterpret_cast<const unsigned char *>(j->data.data());
+    // d[end] is the first byte of the NEXT slice; while it is a continuation
+    // byte (10xxxxxx) the cut sits inside a character, so step back.
+    size_t e = end;
+    for (int guard = 0; guard < 4 && e > off && (d[e] & 0xc0) == 0x80; guard++) {
+      e--;
+    }
+    if (e > off) end = e;
+  }
+
+  sink(reinterpret_cast<const uint8_t *>(j->data.data()) + off, end - off, ctx);
+  return static_cast<double>(end - off);
 }
 
 // Release the slot for reuse. Refuses while the worker is still running, so a

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.jsx → App.tsx}

@@ -1,30 +1,41 @@
 import { useEffect, useState } from "react";
+import { invoke, listen } from "janela/api";
 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([]);
+  const [sum, setSum] = useState<number | null>(null);
+  const [events, setEvents] = useState<string[]>([]);
 
   useEffect(() => {
-    // Backend→frontend events. The payload arrives as a value.
-    janela.listen("added", (value) =>
+    // Backend→frontend events. The payload arrives as a value, and the
+    // generic says which value.
+    listen<number>("added", (value) =>
       setEvents((prev) => [`host emitted: ${value}`, ...prev]),
     );
-    janela.invoke("greet", { name: "__NAME__" }).then(setGreeting);
+    invoke<string>("greet", { name: "__NAME__" }).then(setGreeting);
   }, []);
 
   const add = async () =>
-    setSum(await janela.invoke("add", { a: Number(a), b: Number(b) }));
+    setSum(await invoke<number>("add", { a, 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)} />
+        <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>

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

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

package/templates/solid/files/src-host/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/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,20 @@
-<script>
+<script lang="ts">
+  import { invoke, listen } from "janela/api";
+
   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.
+  listen<number>("added", (value) => (events = [`host emitted: ${value}`, ...events]));
 
-  janela.invoke("greet", { name: "__NAME__" }).then((g) => (greeting = g));
+  invoke<string>("greet", { name: "__NAME__" }).then((g) => (greeting = g));
 
   async function add() {
-    sum = await janela.invoke("add", { a: Number(a), b: Number(b) });
+    sum = await invoke<number>("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

@@ -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/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,23 @@
-<script setup>
+<script setup lang="ts">
 import { onMounted, ref } from "vue";
+import { invoke, listen } from "janela/api";
 
 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}`));
+// 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}`));
 
 onMounted(async () => {
-  greeting.value = await janela.invoke("greet", { name: "__NAME__" });
+  greeting.value = await invoke<string>("greet", { name: "__NAME__" });
 });
 
 async function add() {
-  sum.value = await janela.invoke("add", { a: Number(a.value), b: Number(b.value) });
+  sum.value = await invoke<number>("add", { a: Number(a.value), b: Number(b.value) });
 }
 </script>
 

package/templates/vue/files/src-host/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) => {