winui-svelte 0.0.4 → 0.0.6

package/src/chrome/runtime/port.ts

@@ -0,0 +1,117 @@
+import { ChromeEvent } from "#src/downloads/chrome-event.js";
+import type { Json } from "#src/messaging/json.js";
+
+/** Who opened a port or sent a message: the other context's runtime id. */
+export interface MessageSender {
+  readonly id: string;
+}
+
+/** One way out of a port: the link or the host process behind it. */
+export interface PortEnd {
+  send(message: Json): void;
+  close(): void;
+}
+
+/** What `new Port` takes. */
+export interface PortOptions {
+  readonly name: string;
+  readonly sender?: MessageSender | undefined;
+}
+
+/**
+ * `chrome.runtime.Port`: a long-lived channel. `postMessage` sends,
+ * `onMessage` hears the other end, `onDisconnect` fires once when the other
+ * end goes away or the link fails (`error` then says why, where Chrome sets
+ * `lastError`). A port made by `connect` reaches every other context, so
+ * `onMessage` may hear several and the port ends when all of them have.
+ */
+export class Port {
+  readonly name: string;
+  readonly sender: MessageSender | undefined;
+  readonly onMessage = new ChromeEvent<(message: Json, port: Port) => void>();
+  readonly onDisconnect = new ChromeEvent<(port: Port) => void>();
+  private readonly ends = new Set<PortEnd>();
+  private isClosed = false;
+  private failure: Error | undefined;
+
+  constructor({ name, sender }: PortOptions) {
+    this.name = name;
+    this.sender = sender;
+  }
+
+  /** Why the port ended, when it ended because something failed. */
+  get error() {
+    return this.failure;
+  }
+
+  /**
+   * Sends a JSON value to the other end.
+   *
+   * @param message - What to send.
+   * @throws {Error} When the port is disconnected.
+   */
+  postMessage(message: Json) {
+    if (this.isClosed) {
+      throw new Error("Attempting to use a disconnected port object");
+    }
+
+    for (const end of this.ends) {
+      end.send(message);
+    }
+  }
+
+  /** Ends the port from this side; the other end hears `onDisconnect`, this one does not. */
+  disconnect() {
+    if (this.isClosed) {
+      return;
+    }
+
+    this.isClosed = true;
+    const ends = [...this.ends];
+    this.ends.clear();
+    for (const end of ends) {
+      end.close();
+    }
+  }
+
+  /** Adds a way out; the link calls it. */
+  attach(end: PortEnd) {
+    this.ends.add(end);
+  }
+
+  /** Delivers what the other end sent; the link calls it. */
+  receive(message: Json) {
+    if (!this.isClosed) {
+      this.onMessage.dispatch(message, this);
+    }
+  }
+
+  /**
+   * One way out has gone away; the port ends, and fires `onDisconnect`, when
+   * none is left. The link calls it.
+   */
+  detach({ end, error }: {
+    end: PortEnd;
+    error?: Error | undefined;
+  }) {
+    this.ends.delete(end);
+    const hasEnds = this.ends.size > 0;
+    const isStillOpen = hasEnds || this.isClosed;
+    if (isStillOpen) {
+      return;
+    }
+
+    this.fail(error);
+  }
+
+  /** Ends a port that never got a way out, with the reason. The runtime calls it. */
+  fail(error?: Error) {
+    if (this.isClosed) {
+      return;
+    }
+
+    this.isClosed = true;
+    this.failure = error;
+    this.onDisconnect.dispatch(this);
+  }
+}

package/src/chrome/runtime/runtime.ts

@@ -0,0 +1,317 @@
+import { appUrl, resolveIdentity } from "./identity.ts";
+import type { AppIdentity, IdentitySources } from "./identity.ts";
+import { detectInstalled, fileVersionStore } from "./installed.ts";
+import type { InstalledDetails, VersionStore } from "./installed.ts";
+import { RuntimeLink } from "./link.ts";
+import { MessageEvent } from "./message-event.ts";
+import { connectNativeHost, sendNativeHostMessage } from "./native-host.ts";
+import type { NativeHostSetup } from "./native-host.ts";
+import { Port } from "./port.ts";
+import { relaunch } from "#src/app/relaunch.js";
+import { onStartup } from "#src/app/schedule/events.js";
+import { ChromeEvent } from "#src/downloads/chrome-event.js";
+import type { Json } from "#src/messaging/json.js";
+import type { Transport } from "#src/state/transports/transport.js";
+
+const MANIFEST_VERSION = 3;
+const ARCHITECTURES = new Map([
+  ["x64", "x86-64"],
+  ["arm64", "arm64"],
+  ["ia32", "x86-32"]
+]);
+
+function stopAtProcessExit(listener: () => void) {
+  process.once("exit", listener);
+  return () => process.off("exit", listener);
+}
+
+/** Where the app is running, as `chrome.runtime.getPlatformInfo` reports. */
+export interface PlatformInfo {
+  readonly os: "win";
+  readonly arch: string;
+}
+
+/** Chrome's manifest, as far as an app has one. */
+export interface RuntimeManifest {
+  // eslint-disable-next-line @typescript-eslint/naming-convention -- Chrome's own key
+  readonly manifest_version: typeof MANIFEST_VERSION;
+  readonly name: string;
+  readonly version: string;
+  readonly description?: string | undefined;
+}
+
+/** What `new Runtime` takes; every part has a real default. */
+export interface RuntimeOptions extends IdentitySources, Omit<NativeHostSetup, "id"> {
+  /** Remembers the last version that ran, for `onInstalled`; a file under `%LOCALAPPDATA%` by default. */
+  readonly versionStore?: VersionStore;
+
+  /** A message or request unanswered for this long rejects; unlimited by default. */
+  readonly timeoutMilliseconds?: number;
+
+  /** Starts a new copy of the app and exits this one; `relaunch` of `winui-svelte/app` by default. */
+  readonly relaunchApp?: () => void;
+
+  /**
+   * Subscribes to the end of the process for `onSuspend`; returns how to
+   * stop. `process.once("exit")` by default; `null` subscribes to nothing.
+   */
+  readonly suspendSource?: ((listener: () => void) => () => void) | null;
+
+  /** The CPU architecture name Node reports; `process.arch` by default. */
+  readonly architecture?: string;
+}
+
+/**
+ * `chrome.runtime` for a native app. Contexts of the app (windows, worker
+ * threads) are joined by `addLink` with a transport each; `sendMessage` and
+ * `connect` reach every other linked context, `onMessage` and `onConnect`
+ * hear them. A failure is a rejected promise, or `Port.error`, where Chrome
+ * sets `chrome.runtime.lastError`; there is no `lastError`. `onStartup`
+ * is the one of `winui-svelte/app/schedule`, fired by `startActivation`.
+ *
+ * Nothing runs when this module is imported; make one `Runtime` per context.
+ */
+export class Runtime {
+  /** Fires in a context when another sends a message. */
+  readonly onMessage = new MessageEvent();
+
+  /** Fires in a context when another opens a port to it. */
+  readonly onConnect = new ChromeEvent<(port: Port) => void>();
+
+  /** Fires after `detectInstalled` sees a first run or a new version. */
+  readonly onInstalled = new ChromeEvent<(details: InstalledDetails) => void>();
+
+  /** Fires when the process is about to end; the app cannot be suspended otherwise. */
+  readonly onSuspend = new ChromeEvent<() => void>();
+
+  /** Fires when Windows started the app at sign-in. */
+  readonly onStartup = onStartup;
+
+  private readonly options: RuntimeOptions;
+  private readonly links = new Set<RuntimeLink>();
+  private readonly stopSuspend: (() => void) | undefined;
+  private cachedIdentity: AppIdentity | undefined;
+
+  constructor(options: RuntimeOptions = {}) {
+    this.options = options;
+    const { suspendSource } = options;
+    const source = suspendSource === undefined ? stopAtProcessExit : suspendSource;
+    this.stopSuspend = source?.(() => this.onSuspend.dispatch());
+  }
+
+  /** The app's id: the package family name, or the `package.json` name. */
+  get id() {
+    return this.identity().id;
+  }
+
+  /**
+   * The manifest: name, version and description from the package or
+   * `package.json`.
+   *
+   * @returns Chrome's manifest shape, `manifest_version` 3.
+   */
+  getManifest() {
+    const { name, version, description } = this.identity();
+    return {
+      // eslint-disable-next-line @typescript-eslint/naming-convention -- Chrome's own key
+      manifest_version: MANIFEST_VERSION,
+      name,
+      version,
+      description
+    } satisfies RuntimeManifest;
+  }
+
+  /**
+   * The address of a file in the app: `ms-appx:///path` in a package, a
+   * `file:` URL under the folder of `package.json` otherwise.
+   *
+   * @param relativePath - The file's path inside the app.
+   * @returns The address.
+   */
+  getURL(relativePath: string) {
+    return appUrl({
+      identity: this.identity(),
+      relativePath
+    });
+  }
+
+  /**
+   * Where the app runs.
+   *
+   * @returns The OS (always `win`) and the CPU architecture in Chrome's names.
+   */
+  getPlatformInfo() {
+    const architecture = this.options.architecture ?? process.arch;
+    return {
+      os: "win",
+      arch: ARCHITECTURES.get(architecture) ?? architecture
+    } satisfies PlatformInfo;
+  }
+
+  /**
+   * Joins another context to this one over a transport; the other context
+   * does the same with its end.
+   *
+   * @param transport - A link to the other context (a worker's message port, stdio, memory).
+   * @returns How to leave: closes the transport.
+   */
+  addLink(transport: Transport) {
+    const link = new RuntimeLink({
+      transport,
+      senderId: this.id,
+      timeoutMilliseconds: this.options.timeoutMilliseconds,
+      onMessage: ({ senderId, message }) => this.onMessage.collect({
+        message,
+        sender: {
+          id: senderId
+        }
+      }),
+      onConnect: port => this.onConnect.dispatch(port),
+      onClosed: () => this.links.delete(link)
+    });
+    this.links.add(link);
+    return () => {
+      this.links.delete(link);
+      link.close();
+    };
+  }
+
+  /**
+   * Sends a message to every other linked context and resolves with the
+   * first answer.
+   *
+   * @param message - A JSON value.
+   * @returns What a listener answered, or undefined when listeners heard it
+   *   and none answered.
+   * @throws {Error} When no context is linked or none listens ("Could not
+   *   establish connection. Receiving end does not exist."), or the
+   *   answering listener failed.
+   */
+  async sendMessage(message: Json) {
+    const results = await Promise.allSettled([...this.links].map(link => link.send(message)));
+    const replies = results.flatMap(result => result.status === "fulfilled" ? [result.value] : []);
+    const answered = replies.find(reply => reply.isHandled);
+    const failure = answered?.error ?? null;
+    const hasFailed = failure !== null;
+    if (hasFailed) {
+      throw new Error(failure);
+    }
+
+    const isAnswered = answered !== undefined;
+    if (isAnswered) {
+      return answered.hasResponse ? answered.response : undefined;
+    }
+
+    const hasListener = replies.some(reply => reply.hasListeners);
+    if (hasListener) {
+      return undefined;
+    }
+
+    throw new Error("Could not establish connection. Receiving end does not exist.");
+  }
+
+  /**
+   * Opens a long-lived port to every other linked context.
+   *
+   * @param options - The port's name.
+   * @returns The port; with no context linked it disconnects at once with an
+   *   `error`.
+   */
+  connect({ name = "" }: { name?: string } = {}) {
+    const port = new Port({ name });
+    for (const link of this.links) {
+      link.open({
+        port,
+        name
+      });
+    }
+
+    const hasNoLinks = this.links.size === 0;
+    if (hasNoLinks) {
+      queueMicrotask(() => port.fail(new Error("Could not establish connection. Receiving end does not exist.")));
+    }
+
+    return port;
+  }
+
+  /**
+   * Starts a registered native messaging host and talks to it over a port.
+   *
+   * @param application - The host's name, such as `com.example.host`.
+   * @returns The port, as `Port` says.
+   */
+  connectNative(application: string) {
+    return connectNativeHost({
+      application,
+      ...this.nativeSetup()
+    });
+  }
+
+  /**
+   * Sends one message to a registered native messaging host and resolves
+   * with its first reply.
+   *
+   * @param options - The host's name and the message.
+   * @returns The reply.
+   * @throws {Error} When the host is not found, cannot start, or exits first.
+   */
+  sendNativeMessage({ application, message }: {
+    application: string;
+    message: Json;
+  }) {
+    return sendNativeHostMessage({
+      application,
+      message,
+      ...this.nativeSetup()
+    });
+  }
+
+  /**
+   * Compares the version that last ran with this one, remembers this one and
+   * fires `onInstalled`; call it once at start.
+   *
+   * @returns The details, or null when this version ran before.
+   */
+  async detectInstalled() {
+    const { id, version } = this.identity();
+    const details = await detectInstalled({
+      store: this.options.versionStore ?? fileVersionStore(id),
+      version
+    });
+    const isNew = details !== null;
+    if (isNew) {
+      this.onInstalled.dispatch(details);
+    }
+
+    return details;
+  }
+
+  /** Starts a new copy of the app and exits this one. */
+  reload() {
+    (this.options.relaunchApp ?? relaunch)();
+  }
+
+  /** Closes every link and stops listening for the end of the process. */
+  dispose() {
+    this.stopSuspend?.();
+    for (const link of this.links.values().toArray()) {
+      link.close();
+    }
+
+    this.links.clear();
+  }
+
+  private identity() {
+    this.cachedIdentity ??= resolveIdentity(this.options);
+    return this.cachedIdentity;
+  }
+
+  private nativeSetup() {
+    return {
+      id: this.id,
+      registry: this.options.registry,
+      resolveHost: this.options.resolveHost,
+      spawnHost: this.options.spawnHost
+    } satisfies NativeHostSetup;
+  }
+}

package/src/chrome/storage/chrome-storage.ts

@@ -0,0 +1,120 @@
+import { StorageArea } from "./storage-area.ts";
+import {
+  LOCAL_QUOTA,
+  MANAGED_QUOTA,
+  SESSION_QUOTA,
+  StorageAreaName,
+  SYNC_QUOTA
+} from "./storage-types.ts";
+import type { StorageChanges, StorageQuota } from "./storage-types.ts";
+import { ChromeEvent } from "#src/downloads/chrome-event.js";
+import { appDataFolder, AppDataLocation } from "#src/web-apis/app-data-folder.js";
+import type { AppDataEnvironment } from "#src/web-apis/app-data-folder.js";
+import { atomicFile } from "#src/web-apis/atomic-file.js";
+import type { StorageFile } from "#src/web-apis/atomic-file.js";
+import path from "node:path";
+
+const LOCAL_FILE_NAME = "chrome-storage-local.json";
+const SYNC_FILE_NAME = "chrome-storage-sync.json";
+
+/** What `ChromeStorage` takes. */
+export interface ChromeStorageOptions {
+  /** The folder name under the app data folder; the running program's name by default. */
+  readonly appName?: string;
+
+  /** Where the data folders are; the tests give their own. */
+  readonly environment?: AppDataEnvironment;
+
+  /** Where `local` is kept; a JSON file in the app's local data folder by default. */
+  readonly localFile?: StorageFile;
+
+  /** Where `sync` is kept; a second JSON file next to `local` by default. */
+  readonly syncFile?: StorageFile;
+}
+
+function defaultFile({ options, name }: {
+  options: ChromeStorageOptions;
+  name: string;
+}) {
+  return atomicFile(
+    path.join(
+      appDataFolder({
+        location: AppDataLocation.LOCAL,
+        ...options.appName !== undefined && {
+          appName: options.appName
+        },
+        ...options.environment !== undefined && {
+          environment: options.environment
+        }
+      }), name
+    )
+  );
+}
+
+/**
+ * `chrome.storage` for a Windows app. `local` is a JSON file in the app's
+ * local data folder (the same folder `localStorage` uses), `session` lives in
+ * memory for the life of the process, `managed` is read-only and empty, and
+ * `sync` is a second local file: Windows has no sync service an unpackaged app
+ * can use (roaming settings are deprecated), so values do not reach other PCs,
+ * but the quotas of Chrome's `sync` apply so code meets the same errors. A
+ * change made in another process is not seen. Nothing is read or made until
+ * the first call on an area.
+ */
+export class ChromeStorage {
+  /** Fires with the changes and the area's name after a change in any area. */
+  readonly onChanged = new ChromeEvent<(changes: StorageChanges, areaName: StorageAreaName) => void>();
+  /** Persistent items, kept in a file; 10 MiB. */
+  readonly local: StorageArea;
+  /** Items Chrome would sync; here a second local file, 100 KiB. */
+  readonly sync: StorageArea;
+  /** In-memory items, gone when the process ends; 10 MiB. */
+  readonly session: StorageArea;
+  /** Read-only items set by policy; always empty. */
+  readonly managed: StorageArea;
+
+  /** Made once per app. */
+  constructor(options: ChromeStorageOptions = {}) {
+    this.local = this.areaOf({
+      name: StorageAreaName.LOCAL,
+      file: options.localFile ?? defaultFile({
+        options,
+        name: LOCAL_FILE_NAME
+      }),
+      quota: LOCAL_QUOTA
+    });
+    this.sync = this.areaOf({
+      name: StorageAreaName.SYNC,
+      file: options.syncFile ?? defaultFile({
+        options,
+        name: SYNC_FILE_NAME
+      }),
+      quota: SYNC_QUOTA
+    });
+    this.session = this.areaOf({
+      name: StorageAreaName.SESSION,
+      file: undefined,
+      quota: SESSION_QUOTA
+    });
+    this.managed = this.areaOf({
+      name: StorageAreaName.MANAGED,
+      file: undefined,
+      quota: MANAGED_QUOTA,
+      isReadOnly: true
+    });
+  }
+
+  private areaOf({ name, file, quota, isReadOnly = false }: {
+    name: StorageAreaName;
+    file: StorageFile | undefined;
+    quota: StorageQuota;
+    isReadOnly?: boolean;
+  }) {
+    return new StorageArea({
+      file,
+      quota,
+      isReadOnly,
+      onChange: changes => this.onChanged.dispatch(changes, name)
+    });
+  }
+}

package/src/chrome/storage/index.ts

@@ -0,0 +1,13 @@
+export type { ChromeStorageOptions } from "./chrome-storage.ts";
+export { ChromeStorage } from "./chrome-storage.ts";
+export type { StorageAreaOptions } from "./storage-area.ts";
+export { StorageArea } from "./storage-area.ts";
+export type {
+  StorageChange,
+  StorageChanges,
+  StorageKeyList,
+  StorageKeys,
+  StorageQuota,
+  StoredItems
+} from "./storage-types.ts";
+export { AccessLevel, LOCAL_QUOTA, SESSION_QUOTA, StorageAreaName, SYNC_QUOTA } from "./storage-types.ts";