mirinjs 0.1.0-alpha.2 → 0.1.0-alpha.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mirinjs",
-  "version": "0.1.0-alpha.2",
+  "version": "0.1.0-alpha.20",
   "description": "Build desktop apps with Bun, TypeScript, and Chromium (CEF). The Bun-native Electron alternative.",
   "type": "module",
   "license": "MIT",
@@ -23,7 +23,9 @@
   ],
   "exports": {
     ".": "./src/index.ts",
-    "./config": "./src/config.ts",
+    "./config": "./src/config/index.ts",
+    "./check": "./src/check/index.ts",
+    "./devtools/session": "./src/devtools/session.ts",
     "./rpc": "./src/rpc.ts",
     "./client": "./src/client.ts",
     "./codec": "./src/codec.ts",

package/src/{app.ts → app/facade.ts}

@@ -3,102 +3,59 @@
  * (docs/api-design.md). Talks to the native core through the runtime.
  */
 
-import { runtime, onNativeEvent, resolveUrl, type NativeEvent } from "./runtime.ts";
-import type { Router, EventProc } from "./rpc.ts";
-import type { WindowConfig, WindowMaterial, WindowMaterialOptions } from "./config.ts";
-import { updater } from "./updater.ts";
-import type { Updater } from "./updater.ts";
-import { sidecar as spawnSidecar } from "./sidecar.ts";
-import type { SidecarOptions, SidecarProcess } from "./sidecar.ts";
-
-/** Which native backend a window's `material` resolved to. */
-export type WindowMaterialInfo = {
-  /** The material that was requested. */
-  requested: string;
-  /** What actually rendered: real Liquid Glass, a vibrancy material, or none. */
-  backend: "liquidGlass" | "vibrancy" | "none";
-  /** Whether Apple's Liquid Glass (NSGlassEffectView, macOS 26+) is available. */
-  liquidGlassAvailable: boolean;
-};
-
-export type WindowEvents = {
-  focus: void;
-  blur: void;
-  moved: void;
-  resized: void;
-  closed: void;
-  /** Fired when a native background material is applied (see setMaterial). */
-  material: WindowMaterialInfo;
-};
-
-export type AppEvents = {
-  ready: void;
-  "window-all-closed": void;
-  /** A deep-link URL (a registered `urlSchemes` scheme) opened the app, or
-   *  arrived while it was running. Includes the launch URL. */
-  "open-url": string;
-};
-
-/** A window's frame in screen points (bottom-left origin, like AppKit). */
-export interface WindowFrame {
-  x: number;
-  y: number;
-  width: number;
-  height: number;
-}
-
-type Listener<P> = (payload: P) => void;
-
-class Emitter<Events extends Record<string, unknown>> {
-  #listeners = new Map<keyof Events, Set<Listener<unknown>>>();
+import type { WindowMaterial, WindowMaterialOptions } from "../config/index.ts";
+import type { Router } from "../rpc.ts";
+import { type NativeEvent, onNativeEvent, resolveUrl, runtime } from "../runtime.ts";
+import type { SidecarOptions, SidecarProcess } from "../sidecar.ts";
+import { sidecar as spawnSidecar } from "../sidecar.ts";
+import type { Updater } from "../updater/index.ts";
+import { updater } from "../updater/index.ts";
+import { Emitter } from "./lib/emitter.ts";
+import { normalizeMaterial } from "./lib/material.ts";
+import type {
+  AppEvents,
+  BroadcastEmitters,
+  Dock,
+  ServeHandle,
+  WindowEvents,
+  WindowFrame,
+  WindowMaterialInfo,
+  WindowOpenOptions,
+} from "./types.ts";
 
-  on<K extends keyof Events>(type: K, listener: Listener<Events[K]>): () => void {
-    let set = this.#listeners.get(type);
-    if (!set) this.#listeners.set(type, (set = new Set()));
-    set.add(listener as Listener<unknown>);
-    return () => set!.delete(listener as Listener<unknown>);
-  }
+/** A live, typed handle to an open window. */
+export class WindowHandle extends Emitter<WindowEvents> {
+  readonly id: number;
+  /** Always set: a window opened without a name is given one from its id. */
+  readonly name: string;
+  #url: string;
+  #title: string | undefined;
 
-  async *events<K extends keyof Events>(type: K): AsyncIterableIterator<Events[K]> {
-    const queue: Events[K][] = [];
-    let wake: (() => void) | undefined;
-    const off = this.on(type, (payload) => {
-      queue.push(payload);
-      wake?.();
-    });
-    try {
-      while (true) {
-        while (queue.length) yield queue.shift()!;
-        await new Promise<void>((resolve) => (wake = resolve));
-      }
-    } finally {
-      off();
-    }
+  constructor(id: number, name: string, url = "", title?: string) {
+    super();
+    this.id = id;
+    this.name = name;
+    this.#url = url;
+    this.#title = title;
   }
 
-  protected emit<K extends keyof Events>(type: K, payload: Events[K]): void {
-    this.#listeners.get(type)?.forEach((fn) => fn(payload));
+  /** The URL this window was last asked to load. */
+  get url(): string {
+    return this.#url;
   }
-}
-
-export interface WindowOpenOptions extends WindowConfig {
-  name?: string;
-}
 
-/** A live, typed handle to an open window. */
-export class WindowHandle extends Emitter<WindowEvents> {
-  constructor(
-    readonly id: number,
-    readonly name: string | undefined,
-  ) {
-    super();
+  /** The title this window was last given, if the app set one. */
+  get title(): string | undefined {
+    return this.#title;
   }
 
   async setTitle(title: string): Promise<void> {
+    this.#title = title;
     runtime().core.windowSetTitle(this.id, title);
   }
 
   async loadUrl(url: string): Promise<void> {
+    this.#url = url;
     runtime().core.windowLoadUrl(this.id, url);
   }
 
@@ -182,7 +139,10 @@ export class WindowHandle extends Emitter<WindowEvents> {
   }
 }
 
-type RpcEmitters = Record<string, { emit(payload: unknown): void; broadcast(payload: unknown): void }>;
+type RpcEmitters = Record<
+  string,
+  { emit(payload: unknown): void; broadcast(payload: unknown): void }
+>;
 
 function rpcEmitters(send: (method: string, payload: unknown) => void): RpcEmitters {
   return new Proxy({} as RpcEmitters, {
@@ -195,20 +155,6 @@ function rpcEmitters(send: (method: string, payload: unknown) => void): RpcEmitt
   });
 }
 
-/** Typed push emitters derived from a router's `event` procedures. */
-export type BroadcastEmitters<R extends Router<any>> =
-  R extends Router<infer T>
-    ? {
-        [K in keyof T as T[K] extends EventProc<any> ? K : never]: T[K] extends EventProc<infer P>
-          ? { broadcast(payload: P): void }
-          : never;
-      }
-    : never;
-
-export interface ServeHandle<R extends Router<any>> {
-  readonly rpc: BroadcastEmitters<R>;
-}
-
 class Windows {
   #byName = new Map<string, WindowHandle>();
   #byId = new Map<number, WindowHandle>();
@@ -230,21 +176,24 @@ class Windows {
 
   async open(options: WindowOpenOptions | string): Promise<WindowHandle> {
     const opts = typeof options === "string" ? manifestWindow(options) : options;
+    const url = resolveUrl(opts.url);
     const id = runtime().core.windowCreate(
       JSON.stringify({
         ...opts,
-        url: resolveUrl(opts.url),
+        url,
         material: normalizeMaterial(opts.material),
       }),
     );
-    const handle = new WindowHandle(id, opts.name);
+    // Fall back to an id-derived name so every window is addressable by name, not
+    // just the ones declared in the manifest.
+    const handle = new WindowHandle(id, opts.name ?? `window-${id}`, url, opts.title);
     this.#register(handle);
     return handle;
   }
 
   #register(handle: WindowHandle): void {
     this.#byId.set(handle.id, handle);
-    if (handle.name) this.#byName.set(handle.name, handle);
+    this.#byName.set(handle.name, handle);
   }
 
   /** @internal */
@@ -256,7 +205,8 @@ class Windows {
     const handle = this.#byId.get(id);
     if (handle) {
       this.#byId.delete(id);
-      if (handle.name) this.#byName.delete(handle.name);
+      // Only if it is still the binding: a later window may have taken the name.
+      if (this.#byName.get(handle.name) === handle) this.#byName.delete(handle.name);
     }
   }
 }
@@ -267,28 +217,31 @@ function manifestWindow(name: string): WindowOpenOptions {
   return found;
 }
 
-/** Normalize the `material` option (name or object, or null) to native form. */
-function normalizeMaterial(
-  material: WindowMaterial | WindowMaterialOptions | null | undefined,
-): WindowMaterialOptions | null {
-  if (!material) return null;
-  return typeof material === "string" ? { type: material } : material;
-}
-
-/** macOS Dock-icon controls (no-ops off macOS). */
-export interface Dock {
-  /** Hide the Dock icon and menu-bar presence (agent/accessory app). */
-  hide(): void;
-  /** Restore the Dock icon and menu bar. */
-  show(): void;
-}
-
 class MirinApp extends Emitter<AppEvents> {
   readonly windows = new Windows();
 
-  /** Auto-updater (macOS). Inert unless the app was built with `release` set. */
+  /** Cross-platform auto-updater. Inert unless the app was built with `release` set. */
   readonly updater: Updater = updater;
 
+  /** This app's bundle id (mirin.config `id`). `undefined` when run detached. */
+  get id(): string | undefined {
+    try {
+      return runtime().id;
+    } catch {
+      return undefined;
+    }
+  }
+
+  /** True under `mirin dev`; false in a packaged build (and when detached). Use it
+   *  to keep dev and installed data (caches, databases) separate. */
+  get isDev(): boolean {
+    try {
+      return runtime().isDev;
+    } catch {
+      return false;
+    }
+  }
+
   /** macOS Dock-icon controls. Hiding suits resident, hotkey-summoned apps. */
   readonly dock: Dock = {
     hide: () => this.#setDock(false),
@@ -309,6 +262,7 @@ class MirinApp extends Emitter<AppEvents> {
     }
   }
 
+  /** Type-level `any` preserves the caller's concrete router shape. */
   serve<R extends Router<any>>(router: R): ServeHandle<R> {
     runtime().rpc.setRouter(router);
     return { rpc: this.rpc as BroadcastEmitters<R> };

package/src/app/index.ts

@@ -0,0 +1,2 @@
+export * from "./facade.ts";
+export * from "./types.ts";

package/src/app/lib/emitter.ts

@@ -0,0 +1,40 @@
+type Listener<P> = (payload: P) => void;
+
+export class Emitter<Events extends Record<string, unknown>> {
+  #listeners = new Map<keyof Events, Set<Listener<unknown>>>();
+
+  on<K extends keyof Events>(type: K, listener: Listener<Events[K]>): () => void {
+    let set = this.#listeners.get(type);
+    if (!set) {
+      set = new Set();
+      this.#listeners.set(type, set);
+    }
+    set.add(listener as Listener<unknown>);
+    return () => {
+      set.delete(listener as Listener<unknown>);
+    };
+  }
+
+  async *events<K extends keyof Events>(type: K): AsyncIterableIterator<Events[K]> {
+    const queue: Events[K][] = [];
+    let wake: (() => void) | undefined;
+    const off = this.on(type, (payload) => {
+      queue.push(payload);
+      wake?.();
+    });
+    try {
+      while (true) {
+        while (queue.length) yield queue.shift()!;
+        await new Promise<void>((resolve) => {
+          wake = resolve;
+        });
+      }
+    } finally {
+      off();
+    }
+  }
+
+  protected emit<K extends keyof Events>(type: K, payload: Events[K]): void {
+    for (const fn of this.#listeners.get(type) ?? []) fn(payload);
+  }
+}

package/src/app/lib/material.ts

@@ -0,0 +1,9 @@
+import type { WindowMaterial, WindowMaterialOptions } from "../../config/index.ts";
+
+/** Normalize the `material` option (name or object, or null) to native form. */
+export function normalizeMaterial(
+  material: WindowMaterial | WindowMaterialOptions | null | undefined,
+): WindowMaterialOptions | null {
+  if (!material) return null;
+  return typeof material === "string" ? { type: material } : material;
+}

package/src/app/types.ts

@@ -0,0 +1,65 @@
+import type { WindowConfig } from "../config/index.ts";
+import type { EventProc, Router } from "../rpc.ts";
+
+/** Which native backend a window's `material` resolved to. */
+export type WindowMaterialInfo = {
+  /** The material that was requested. */
+  requested: string;
+  /** What actually rendered: real Liquid Glass, a vibrancy material, or none. */
+  backend: "liquidGlass" | "vibrancy" | "none";
+  /** Whether Apple's Liquid Glass (NSGlassEffectView, macOS 26+) is available. */
+  liquidGlassAvailable: boolean;
+};
+
+export type WindowEvents = {
+  focus: void;
+  blur: void;
+  moved: void;
+  resized: void;
+  closed: void;
+  /** Fired when a native background material is applied (see setMaterial). */
+  material: WindowMaterialInfo;
+};
+
+export type AppEvents = {
+  ready: void;
+  "window-all-closed": void;
+  /** A deep-link URL (a registered `urlSchemes` scheme) opened the app, or
+   *  arrived while it was running. Includes the launch URL. */
+  "open-url": string;
+};
+
+/** A window's frame in screen points (bottom-left origin, like AppKit). */
+export interface WindowFrame {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface WindowOpenOptions extends WindowConfig {
+  name?: string;
+}
+
+/** Typed push emitters derived from a router's `event` procedures.
+ * Type-level `any` keeps the caller's router payload inference intact. */
+export type BroadcastEmitters<R extends Router<any>> = R extends Router<infer T>
+  ? {
+      [K in keyof T as T[K] extends EventProc<any> ? K : never]: T[K] extends EventProc<infer P>
+        ? { broadcast(payload: P): void }
+        : never;
+    }
+  : never;
+
+/** Type-level `any` preserves the caller's concrete router shape. */
+export interface ServeHandle<R extends Router<any>> {
+  readonly rpc: BroadcastEmitters<R>;
+}
+
+/** macOS Dock-icon controls (no-ops off macOS). */
+export interface Dock {
+  /** Hide the Dock icon and menu-bar presence (agent/accessory app). */
+  hide(): void;
+  /** Restore the Dock icon and menu bar. */
+  show(): void;
+}

package/src/check/define.ts

@@ -0,0 +1,24 @@
+import type { CheckScenario } from "./types.ts";
+
+/**
+ * Declare a `mirin check` scenario. Default-export the result from the file you
+ * pass to `mirin check --scenario`.
+ *
+ * ```ts
+ * import { defineCheck } from "mirinjs/check";
+ *
+ * export default defineCheck(async (app) => {
+ *   app.step("add a todo");
+ *   await app.click("text=add a todo");
+ *   await app.type("ship it");
+ *   await app.click("text=Add");
+ *   await app.expectText("ship it");
+ * });
+ * ```
+ *
+ * Identity at runtime — its whole job is to type the callback, so `app` is
+ * inferred without the file having to annotate it.
+ */
+export function defineCheck(scenario: CheckScenario): CheckScenario {
+  return scenario;
+}

package/src/check/index.ts

@@ -0,0 +1,2 @@
+export { defineCheck } from "./define.ts";
+export type { CheckDriver, CheckScenario, CheckWindow, WindowTarget } from "./types.ts";

package/src/check/types.ts

@@ -0,0 +1,95 @@
+/**
+ * The contract a `mirin check` scenario is written against. Types live in the
+ * runtime package so an app can import them without the CLI's internals; the
+ * implementation lives in the CLI, which holds the inspector connection.
+ */
+
+import type { DevEvent, DevEventQuery } from "../devtools/types.ts";
+
+/** A window as the scenario sees it. */
+export interface CheckWindow {
+  id: number;
+  name: string;
+  url?: string;
+  title?: string;
+}
+
+/** Which window an action targets. Omit when the app has only one. */
+export interface WindowTarget {
+  window?: number;
+}
+
+/**
+ * The app under check. Every method talks to the running app's inspector.
+ * Anything that cannot be done rejects, and an unhandled rejection fails the check.
+ */
+export interface CheckDriver {
+  /** Click an element. Selectors accept CSS or `text=Save`. */
+  click(selector: string, options?: WindowTarget & { clickCount?: number }): Promise<void>;
+  /** Type text, optionally focusing `selector` first. */
+  type(text: string, options?: WindowTarget & { selector?: string }): Promise<void>;
+  /** Press a named key, e.g. `Enter`, `Escape`, `Tab`. */
+  key(name: string, options?: WindowTarget): Promise<void>;
+  scroll(options: WindowTarget & { deltaY?: number; deltaX?: number }): Promise<void>;
+  /** Wait for a selector to match, rejecting if it never does. */
+  waitFor(selector: string, options?: WindowTarget & { timeoutMs?: number }): Promise<void>;
+  /** Wait a fixed time. Prefer `waitFor` — a sleep is a guess. */
+  sleep(ms: number): Promise<void>;
+
+  /** The accessibility tree, or the DOM with `format: "dom"`. */
+  snapshot(options?: WindowTarget & { format?: "ax" | "dom" }): Promise<string>;
+  /** Evaluate an expression in the page and return its value. */
+  evaluate<T = unknown>(expression: string, options?: WindowTarget): Promise<T>;
+  /** Capture a screenshot into the session dir; returns its path. */
+  screenshot(label?: string, options?: WindowTarget): Promise<string>;
+  windows(): Promise<CheckWindow[]>;
+  /** Slices the app published with `devtools.expose`. */
+  exposed(): Promise<Record<string, unknown>>;
+  /** The event stream so far, filtered the same way as the inspector's `/logs`. */
+  logs(query?: DevEventQuery): Promise<DevEvent[]>;
+  /**
+   * Send a raw DevTools-protocol command, for anything the methods above do not cover.
+   *
+   * ```ts
+   * const [call] = await app.logs({ type: "network.response", contains: "/api/todos" });
+   * const body = await app.cdp<{ body: string }>("Network.getResponseBody", {
+   *   requestId: call.data.requestId,
+   * });
+   * ```
+   */
+  cdp<T = Record<string, unknown>>(
+    method: string,
+    params?: Record<string, unknown>,
+    options?: WindowTarget,
+  ): Promise<T>;
+
+  /** Fail the check unless `condition` is truthy, right now. After an interaction,
+   *  prefer `waitUntil` — the RPC round trip has not landed yet. */
+  assert(condition: unknown, message: string): asserts condition;
+  /**
+   * Poll `condition` until it holds, failing the check with `message` if it never
+   * does. The general form of `expectText`.
+   *
+   * ```ts
+   * await app.waitUntil(
+   *   async () => (await app.evaluate<number>("todos.length")) > 0,
+   *   "the todo never reached the list",
+   * );
+   * ```
+   */
+  waitUntil(
+    condition: () => Promise<unknown> | unknown,
+    message: string,
+    options?: { timeoutMs?: number },
+  ): Promise<void>;
+  /** Fail the check unless the window's accessibility tree contains `text`. Polls
+   *  until the timeout (2s by default): a single read would be flaky by construction. */
+  expectText(text: string, options?: WindowTarget & { timeoutMs?: number }): Promise<void>;
+
+  /** Name the phase the scenario is in. Steps appear in the report and the event
+   *  stream, so a failure says which step it happened in. */
+  step(name: string): void;
+}
+
+/** A scenario: drive the app, throw to fail. */
+export type CheckScenario = (app: CheckDriver) => Promise<void> | void;

package/src/client.ts

@@ -7,18 +7,18 @@
 
 import type { EventProc, MutationProc, QueryProc, Router } from "./rpc.ts";
 
-export type ClientFor<R extends Router<any>> =
-  R extends Router<infer T>
-    ? {
-        [K in keyof T]: T[K] extends QueryProc<infer I, infer O>
+// Type-level `any` preserves the app router's concrete procedure inference for UI callers.
+export type ClientFor<R extends Router<any>> = R extends Router<infer T>
+  ? {
+      [K in keyof T]: T[K] extends QueryProc<infer I, infer O>
+        ? (input: I) => Promise<Awaited<O>>
+        : T[K] extends MutationProc<infer I, infer O>
           ? (input: I) => Promise<Awaited<O>>
-          : T[K] extends MutationProc<infer I, infer O>
-            ? (input: I) => Promise<Awaited<O>>
-            : T[K] extends EventProc<infer P>
-              ? { on(listener: (payload: P) => void): () => void }
-              : never;
-      }
-    : never;
+          : T[K] extends EventProc<infer P>
+            ? { on(listener: (payload: P) => void): () => void }
+            : never;
+    }
+  : never;
 
 interface MirinTransport {
   call(method: string, input: unknown): Promise<unknown>;
@@ -49,6 +49,7 @@ function transport(): MirinTransport {
  * Create the typed client for the app's router. Pass the Router *type* only —
  * never import the router value (and its handlers) into UI code.
  */
+// Type-level `any` keeps `client<AppRouter>()` inference intact.
 export function client<R extends Router<any>>(): ClientFor<R> {
   const eventCache = new Map<string, { on(l: (p: unknown) => void): () => void }>();
 

package/src/config/index.ts

@@ -0,0 +1 @@
+export * from "./manifest.ts";