overmux 0.0.1 → 0.0.2

package/src/internal/client/background-notifications.ts

@@ -0,0 +1,194 @@
+// Provides the browser API and controls for background notifications.
+// Browser PushManager details remain inside this delivery boundary.
+import {
+  backgroundNotificationPublicKeyResponseSchema,
+  backgroundNotificationSubscriptionSchema,
+} from "../shared/index";
+
+const enabledStorageKey = "overmux.backgroundNotificationsEnabled";
+
+export type BackgroundNotificationStatus =
+  | "checking"
+  | "denied"
+  | "disabled"
+  | "enabled"
+  | "error"
+  | "ios-home-screen"
+  | "unsupported";
+
+const isIos = () =>
+  /iPad|iPhone|iPod/u.test(navigator.userAgent) ||
+  (navigator.platform === "MacIntel" && navigator.maxTouchPoints > 1);
+const isStandalone = () =>
+  window.matchMedia("(display-mode: standalone)").matches ||
+  Boolean((navigator as Navigator & { standalone?: boolean }).standalone);
+
+const supportStatus = (): BackgroundNotificationStatus | undefined => {
+  if (window.overmuxHost?.notifications) {
+    return "unsupported";
+  }
+  if (isIos() && !isStandalone()) {
+    return "ios-home-screen";
+  }
+  if (
+    !window.isSecureContext ||
+    !("Notification" in window) ||
+    !("serviceWorker" in navigator) ||
+    !("PushManager" in window)
+  ) {
+    return "unsupported";
+  }
+  return undefined;
+};
+
+const decodeApplicationServerKey = (value: string) => {
+  const padded = `${value}${"=".repeat((4 - (value.length % 4)) % 4)}`;
+  return Uint8Array.from(
+    atob(padded.replaceAll("-", "+").replaceAll("_", "/")),
+    (character) => character.charCodeAt(0),
+  );
+};
+
+const encodeApplicationServerKey = (value: ArrayBuffer | null) => {
+  if (!value) {
+    return undefined;
+  }
+  const binary = String.fromCharCode(...new Uint8Array(value));
+  return btoa(binary)
+    .replaceAll("+", "-")
+    .replaceAll("/", "_")
+    .replace(/=+$/u, "");
+};
+
+const request = async (path: string, init?: RequestInit) => {
+  const response = await fetch(path, { cache: "no-store", ...init });
+  if (!response.ok) {
+    throw new Error(
+      `Background notification request failed: ${response.status}`,
+    );
+  }
+  return response;
+};
+
+const getPublicKey = async () => {
+  const response = await request("/api/background-notifications/public-key");
+  return backgroundNotificationPublicKeyResponseSchema.parse(
+    await response.json(),
+  ).publicKey;
+};
+
+const serializeSubscription = (subscription: PushSubscription) => {
+  const json = subscription.toJSON();
+  return backgroundNotificationSubscriptionSchema.parse({
+    endpoint: subscription.endpoint,
+    expirationTime: subscription.expirationTime ?? null,
+    keys: json.keys,
+  });
+};
+
+const enableSubscription = async (subscription: PushSubscription) => {
+  await request("/api/background-notifications/subscription", {
+    body: JSON.stringify(serializeSubscription(subscription)),
+    headers: { "Content-Type": "application/json" },
+    method: "PUT",
+  });
+};
+
+const disableSubscription = async (subscription: PushSubscription) => {
+  await request("/api/background-notifications/subscription", {
+    body: JSON.stringify({ endpoint: subscription.endpoint }),
+    headers: { "Content-Type": "application/json" },
+    method: "DELETE",
+  });
+};
+
+const subscribe = async (
+  registration: ServiceWorkerRegistration,
+  publicKey: string,
+) =>
+  registration.pushManager.subscribe({
+    applicationServerKey: decodeApplicationServerKey(publicKey),
+    userVisibleOnly: true,
+  });
+
+const canManageSubscription = () =>
+  window.isSecureContext &&
+  "serviceWorker" in navigator &&
+  "PushManager" in window;
+
+const removeCurrentSubscription = async () => {
+  if (!canManageSubscription()) {
+    return;
+  }
+  const registration = await navigator.serviceWorker.getRegistration();
+  const subscription = await registration?.pushManager.getSubscription();
+  if (!subscription) {
+    return;
+  }
+  await disableSubscription(subscription);
+  if (!(await subscription.unsubscribe())) {
+    throw new Error("The background subscription could not be removed");
+  }
+};
+
+const reconcileBackgroundNotifications = async () => {
+  const registration = await navigator.serviceWorker.ready;
+  const publicKey = await getPublicKey();
+  let subscription = await registration.pushManager.getSubscription();
+  const subscriptionKey = subscription
+    ? encodeApplicationServerKey(subscription.options.applicationServerKey)
+    : undefined;
+  if (subscription && subscriptionKey !== publicKey) {
+    await disableSubscription(subscription);
+    if (!(await subscription.unsubscribe())) {
+      throw new Error("The previous background subscription is still active");
+    }
+    subscription = null;
+  }
+  if (!subscription) {
+    subscription = await subscribe(registration, publicKey);
+  }
+  await enableSubscription(subscription);
+};
+
+export const enableBackgroundNotifications = async () => {
+  if (supportStatus()) {
+    localStorage.removeItem(enabledStorageKey);
+    return false;
+  }
+  const permission =
+    Notification.permission === "default"
+      ? await Notification.requestPermission()
+      : Notification.permission;
+  if (permission !== "granted") {
+    localStorage.removeItem(enabledStorageKey);
+    return false;
+  }
+  await reconcileBackgroundNotifications();
+  localStorage.setItem(enabledStorageKey, "true");
+  return true;
+};
+
+export const disableBackgroundNotifications = async () => {
+  localStorage.removeItem(enabledStorageKey);
+  await removeCurrentSubscription();
+};
+
+export const reconciledStatus =
+  async (): Promise<BackgroundNotificationStatus> => {
+    const unavailable = supportStatus();
+    if (unavailable) {
+      await disableBackgroundNotifications().catch(() => undefined);
+      return unavailable;
+    }
+    if (Notification.permission !== "granted") {
+      await disableBackgroundNotifications().catch(() => undefined);
+      return Notification.permission === "denied" ? "denied" : "disabled";
+    }
+    if (localStorage.getItem(enabledStorageKey) !== "true") {
+      await disableBackgroundNotifications();
+      return "disabled";
+    }
+    await reconcileBackgroundNotifications();
+    return "enabled";
+  };

package/src/internal/client/browser-api.ts

@@ -0,0 +1,97 @@
+import type { RuntimeManifest } from "../shared/index";
+import type { ContractInputArguments } from "../../public/index";
+import type { z } from "zod";
+
+import type { ClientTransport } from "./transport";
+
+type Operations<TConfig> = TConfig extends { operations?: infer TOperations }
+  ? NonNullable<TOperations>
+  : never;
+type InputOf<T> = T extends { input: infer TInput extends z.ZodType }
+  ? TInput
+  : never;
+type OutputOf<T> = T extends { output: infer TOutput extends z.ZodType }
+  ? z.output<TOutput>
+  : never;
+type OperationId<TConfig> = Extract<keyof Operations<TConfig>, string>;
+type OperationInput<TConfig, TId extends OperationId<TConfig>> = InputOf<
+  Operations<TConfig>[TId]
+>;
+type OperationOutput<TConfig, TId extends OperationId<TConfig>> = OutputOf<
+  Operations<TConfig>[TId]
+>;
+type OperationArguments<TInput extends z.ZodType> = [
+  ...ContractInputArguments<TInput>,
+  signal?: AbortSignal,
+];
+
+export type OvermuxServerApi<TServerConfig> = {
+  executeOperation: <TId extends OperationId<TServerConfig>>(
+    id: TId,
+    ...args: OperationArguments<OperationInput<TServerConfig, TId>>
+  ) => Promise<OperationOutput<TServerConfig, TId>>;
+};
+
+export type RuntimeOvermuxServerApi = {
+  executeOperation: (
+    id: string,
+    input?: unknown,
+    signal?: AbortSignal,
+  ) => Promise<unknown>;
+  openStream: (input: {
+    id: string;
+    input?: unknown;
+    onClose: () => void;
+    onError: (error: Error) => void;
+    onMessage: (message: unknown) => void;
+    onOpen: () => void;
+  }) => { close: () => void; send: (message: unknown) => boolean };
+  readResource: (input: { id: string; input?: unknown }) => Promise<unknown>;
+  subscribeResource: (input: {
+    id: string;
+    input?: unknown;
+    onError: (error: Error) => void;
+    onInvalidate: () => void;
+  }) => () => void;
+};
+
+const availableName = (
+  names: readonly string[],
+  kind: "Resource" | "Stream",
+  name: string,
+) => {
+  if (!names.includes(name)) {
+    throw new Error(`${kind} is not available: ${name}`);
+  }
+  return name;
+};
+
+export const createOvermuxServerApi = ({
+  manifest,
+  transport,
+}: {
+  manifest: RuntimeManifest;
+  transport: ClientTransport;
+}): RuntimeOvermuxServerApi => ({
+  executeOperation: (id, input, signal) => {
+    if (!manifest.operations.includes(id)) {
+      throw new Error(`Operation is not available: ${id}`);
+    }
+    return transport.invokeOperation({ input, name: id, signal });
+  },
+  openStream: ({ id, ...input }) =>
+    transport.openStream({
+      ...input,
+      streamName: availableName(manifest.streams, "Stream", id),
+    }),
+  readResource: ({ id, input }) =>
+    transport.readResource({
+      input,
+      resourceName: availableName(manifest.resources, "Resource", id),
+    }),
+  subscribeResource: ({ id, ...input }) =>
+    transport.subscribeResource({
+      ...input,
+      resourceName: availableName(manifest.resources, "Resource", id),
+    }),
+});

package/src/internal/client/client-definition.ts

@@ -0,0 +1,184 @@
+import type { OvermuxContrast, OvermuxScheme } from "./theme-scope";
+import type { ComponentType } from "react";
+import {
+  formatKeyBinding,
+  keyBindingSchema,
+  matchesKeyBinding,
+  type KeyBinding,
+} from "@overmux/keybindings";
+export {
+  formatKeyBinding,
+  keyBindingSchema,
+  matchesKeyBinding,
+} from "@overmux/keybindings";
+export type { KeyBinding } from "@overmux/keybindings";
+import { z } from "zod";
+
+import type { OvermuxServerApi } from "./browser-api";
+
+export type KeySequence = readonly [KeyBinding, KeyBinding, ...KeyBinding[]];
+export type ShortcutBinding = KeyBinding | KeySequence;
+export type ConditionalShortcutBinding = {
+  binding: ShortcutBinding;
+  when: { media: string };
+};
+export type CommandBinding = ShortcutBinding | ConditionalShortcutBinding;
+export type ChordPrefix = {
+  binding: KeyBinding;
+  unmatched: "replay-to-focused-input";
+};
+
+export const shortcutBindingSchema = z.union([
+  keyBindingSchema,
+  z.array(keyBindingSchema).min(2),
+]);
+export const commandBindingSchema = z.union([
+  shortcutBindingSchema,
+  z.object({
+    binding: shortcutBindingSchema,
+    when: z.object({ media: z.string().trim().min(1) }),
+  }),
+]);
+export const chordPrefixSchema = z.object({
+  binding: keyBindingSchema,
+  unmatched: z.literal("replay-to-focused-input"),
+});
+
+export const formatShortcutBinding = (binding: ShortcutBinding) =>
+  typeof binding === "string"
+    ? formatKeyBinding(binding)
+    : binding.map(formatKeyBinding).join(" ");
+
+type CommandRunResult = Promise<unknown> | unknown;
+type CommandRun<TServerConfig, TParams> = (input: {
+  overmuxServerApi: OvermuxServerApi<TServerConfig>;
+  params: TParams;
+}) => CommandRunResult;
+type CommandDefinitionSource = {
+  defaultBindings?: readonly CommandBinding[];
+  params?: z.ZodType;
+  run?: unknown;
+  title: string;
+};
+type ParamsSchema<TCommand> = TCommand extends {
+  params: infer TParams extends z.ZodType;
+}
+  ? TParams
+  : undefined;
+type ParamsOutput<TCommand> =
+  ParamsSchema<TCommand> extends z.ZodType
+    ? z.output<ParamsSchema<TCommand>>
+    : undefined;
+type CheckedCommand<TServerConfig, TCommand extends CommandDefinitionSource> = {
+  [TKey in keyof TCommand]: TKey extends "run"
+    ? CommandRun<TServerConfig, ParamsOutput<TCommand>>
+    : TCommand[TKey];
+} & {
+  defaultBindings?: readonly CommandBinding[];
+  params?: z.ZodType;
+  title: string;
+};
+type CheckedCommands<
+  TServerConfig,
+  TCommands extends Record<string, CommandDefinitionSource>,
+> = {
+  [TId in keyof TCommands]: CheckedCommand<TServerConfig, TCommands[TId]>;
+};
+
+export type CommandHandle<TId extends string = string> = {
+  defaultBindings?: readonly CommandBinding[];
+  id: TId;
+  params?: z.ZodType;
+  run?: unknown;
+  title: string;
+};
+
+type DefinedCommands<
+  TServerConfig,
+  TCommands extends Record<string, CommandDefinitionSource>,
+> = {
+  readonly [TId in keyof TCommands]: CheckedCommand<
+    TServerConfig,
+    TCommands[TId]
+  > & { readonly id: Extract<TId, string> };
+};
+
+const validateBindings = (bindings: readonly CommandBinding[] | undefined) =>
+  bindings?.forEach((binding) => commandBindingSchema.parse(binding));
+
+export const defineCommandRegistry =
+  <TServerConfig>() =>
+  <const TCommands extends Record<string, CommandDefinitionSource>>(
+    commands: CheckedCommands<TServerConfig, TCommands>,
+  ): DefinedCommands<TServerConfig, TCommands> =>
+    Object.fromEntries(
+      Object.entries(commands).map(([id, command]) => {
+        validateBindings(command.defaultBindings);
+        return [id, { ...command, id }];
+      }),
+    ) as DefinedCommands<TServerConfig, TCommands>;
+
+export type CommandRegistry = Readonly<Record<string, CommandHandle>>;
+
+export type OvermuxClientAppearance = {
+  contrast?: OvermuxContrast;
+  scheme?: OvermuxScheme;
+};
+
+export type ClientAppDefinition<
+  TCommands extends CommandRegistry = CommandRegistry,
+> = {
+  appearance?: OvermuxClientAppearance;
+  chordPrefixes?: readonly ChordPrefix[];
+  commands: TCommands;
+  component: ComponentType;
+  shortcutOverrides?: Partial<
+    Record<Extract<keyof TCommands, string>, readonly CommandBinding[]>
+  >;
+};
+
+export const defineOvermuxClient = <const TCommands extends CommandRegistry>(
+  definition: ClientAppDefinition<TCommands>,
+): ClientAppDefinition<TCommands> => {
+  definition.chordPrefixes?.forEach((prefix) =>
+    chordPrefixSchema.parse(prefix),
+  );
+  Object.values(definition.shortcutOverrides ?? {}).forEach(validateBindings);
+  return definition;
+};
+
+export const isConditionalShortcutBinding = (
+  binding: CommandBinding,
+): binding is ConditionalShortcutBinding =>
+  typeof binding !== "string" && !Array.isArray(binding);
+
+export const resolveShortcutBinding = (
+  binding: CommandBinding,
+): ShortcutBinding =>
+  isConditionalShortcutBinding(binding) ? binding.binding : binding;
+
+export const configuredCommandBindings = (
+  definition: ClientAppDefinition,
+  command: CommandHandle,
+) =>
+  definition.shortcutOverrides?.[command.id] ?? command.defaultBindings ?? [];
+
+export const activeCommandBindings = (
+  bindings: readonly CommandBinding[],
+  matchesMedia: (media: string) => boolean,
+) =>
+  bindings.flatMap((binding) =>
+    !isConditionalShortcutBinding(binding) || matchesMedia(binding.when.media)
+      ? [resolveShortcutBinding(binding)]
+      : [],
+  );
+
+export const shortcutMediaQueries = (definition: ClientAppDefinition) => [
+  ...new Set(
+    Object.values(definition.commands).flatMap((command) =>
+      configuredCommandBindings(definition, command).flatMap((binding) =>
+        isConditionalShortcutBinding(binding) ? [binding.when.media] : [],
+      ),
+    ),
+  ),
+];