@legendapp/spark 0.0.1-next.2 → 0.0.1-next.4

package/vendor/node_modules/@legendapp/spark-native-menu/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@legendapp/spark-native-menu",
-  "version": "0.0.1-next.2",
+  "version": "0.0.1-next.4",
   "main": "src/index",
   "react-native": "src/index",
   "codegenConfig": {
@@ -13,7 +13,8 @@
     "ios": {
       "modulesProvider": {
         "NativeMenu": "RNNativeMenu"
-      }
+      },
+      "componentProvider": {}
     }
   },
   "peerDependencies": {
@@ -24,7 +25,8 @@
   "files": [
     "src",
     "ios",
-    "*.podspec"
+    "*.podspec",
+    "macos"
   ],
   "spark": {
     "sdk": true,
@@ -37,5 +39,8 @@
     ],
     "requires": []
   },
-  "private": true
+  "private": true,
+  "dependencies": {
+    "@legendapp/spark-desktop-app": "0.0.1-next.4"
+  }
 }

package/vendor/node_modules/@legendapp/spark-native-menu/src/NativeMenu.ts

@@ -1,13 +1,8 @@
 import type { TurboModule } from "react-native";
 import { TurboModuleRegistry } from "react-native";
-
 export interface Spec extends TurboModule {
-  configureMenus(ownerId: string, menusJson: string): void;
-  updateMenuItems(ownerId: string, patchesJson: string): void;
-  clearMenus(ownerId: string): void;
-  clearAllMenus(): void;
+  publish(menusJson: string): Promise<void>;
   addListener(eventName: string): void;
   removeListeners(count: number): void;
 }
-
-export default TurboModuleRegistry.getEnforcing<Spec>("NativeMenu");
+export default TurboModuleRegistry.get<Spec>("NativeMenu");

package/vendor/node_modules/@legendapp/spark-native-menu/src/api.ts

@@ -1,128 +1,83 @@
 import { NativeEventEmitter, Platform } from "react-native";
-import { useEffect } from "react";
 import NativeMenu from "./NativeMenu";
-import { composeWindowsMenus, patchWindowsMenus } from "./windows-menus";
-
-export type NativeMenuShortcut = {
-  key: string;
-  modifiers?: number;
-};
-
-export type NativeMenuItemPlacement = {
-  before?: string;
-  after?: string;
-};
-
-export const commandModifier = 1 << 20;
-export const optionModifier = 1 << 19;
-export const shiftModifier = 1 << 17;
-export const settingsTargetTitles = ["Settings...", "Settings…", "Preferences...", "Preferences…"];
-export const openTargetTitles = ["Open", "Open...", "Open…"];
-export const saveTargetTitles = ["Save", "Save...", "Save…"];
-export const saveAsTargetTitles = ["Save As", "Save As...", "Save As…"];
-
-export type NativeMenuItem = {
-  id: string;
-  title?: string;
-  targetTitle?: string;
-  targetTitles?: string[];
-  /** Nested native system-menu paths are macOS-only. Windows accepts one item title. */
-  targetPath?: string[];
-  enabled?: boolean;
-  checked?: boolean;
-  hidden?: boolean;
-  placement?: NativeMenuItemPlacement;
-  separator?: boolean;
-  shortcut?: NativeMenuShortcut | null;
-  payload?: Record<string, unknown>;
-};
-
-export type NativeMenuConfig = {
-  id: string;
-  title: string;
-  systemMenu?: "app";
-  placement?: {
-    before?: string;
-    after?: string;
-  };
-  items: NativeMenuItem[];
-};
-
-export type NativeMenuItemPatch = Omit<Partial<NativeMenuItem>, "separator"> & {
-  id: string;
-};
-
-export type NativeMenuAction = {
-  ownerId: string;
-  menuId: string;
-  itemId: string;
-  payload?: Record<string, unknown>;
-};
-
-export type NativeMenuActionHandlers = Record<string, (action: NativeMenuAction) => void>;
-
-export type UseNativeMenuOptions = {
-  handlers?: NativeMenuActionHandlers;
-  menus: NativeMenuConfig[];
-  onAction?: (action: NativeMenuAction) => void;
-  ownerId: string;
-};
-
-const windowsOwners = new Map<string, NativeMenuConfig[]>();
-function publishWindowsMenus(next: Map<string, NativeMenuConfig[]>) {
-  // Composition can reject unsupported targets. Preserve the last good owners
-  // and native menu when a proposed contribution is invalid.
-  const composed = composeWindowsMenus(next);
-  NativeMenu.configureMenus("spark.windows.menus", JSON.stringify(composed));
-  windowsOwners.clear(); for (const [owner, menus] of next) windowsOwners.set(owner, menus);
-}
-export function configureMenus(ownerId: string, menus: NativeMenuConfig[]) {
-  if (Platform.OS === "windows") { const next = new Map(windowsOwners); next.set(ownerId, JSON.parse(JSON.stringify(menus))); publishWindowsMenus(next); }
-  else if (Platform.OS === "macos") NativeMenu.configureMenus(ownerId, JSON.stringify(menus));
+import { SparkError, asyncRegistration, invokeNative, type Availability, type AsyncRegistration } from "@legendapp/spark-desktop-app/src/contracts";
+import { menuItems, selectableMenuIds, type MenuItem as SharedMenuItem, type MenuItemTree, type MenuWireItem, type MenuAction as SharedMenuAction } from "@legendapp/spark-desktop-app/src/contracts/menu";
+import { composeWindowsMenus } from "./windows-menus";
+type NativeMenuLeaf = Extract<SharedMenuItem, { type: "action" | "checkbox" | "separator" | "role" }>;
+export type MenuItem = MenuItemTree<NativeMenuLeaf>;
+export type MenuAction = Extract<SharedMenuAction, { type: "action" }>;
+export type { MenuIcon, MenuRole, MenuTarget, MenuPlacement, MenuLocation } from "@legendapp/spark-desktop-app/src/contracts/menu";
+export type { AsyncRegistration } from "@legendapp/spark-desktop-app/src/contracts";
+export type MenuRootItem = Extract<MenuItem, { type: "submenu" }>;
+export interface MenuUpdate { items: readonly MenuRootItem[] }
+export interface MenuOptions extends MenuUpdate { id: string; onAction?: (action: MenuAction) => void }
+export interface Menu extends AsyncRegistration { readonly id: string; update(options: MenuUpdate): Promise<void> }
+interface Owner { id: string; token: string; items: MenuWireItem[] }
+let owners = new Map<string, Owner>();
+let sequence = 0, queue: Promise<unknown> = Promise.resolve();
+function serial<T>(operation: () => Promise<T>): Promise<T> { const result = queue.then(operation); queue = result.catch(() => {}); return result; }
+export function getMenuAvailability(): Availability {
+  if (Platform.OS !== "macos" && Platform.OS !== "windows") return { available: false, reason: "unsupported-platform" };
+  return NativeMenu ? { available: true } : { available: false, reason: "missing-module" };
 }
-export function updateMenuItems(ownerId: string, patches: NativeMenuItemPatch[]) {
-  if (Platform.OS === "windows") {
-    const menus = windowsOwners.get(ownerId); if (menus) { const next = new Map(windowsOwners); next.set(ownerId, patchWindowsMenus(menus, patches)); publishWindowsMenus(next); }
-  } else if (Platform.OS === "macos") NativeMenu.updateMenuItems(ownerId, JSON.stringify(patches));
+function available() {
+  const availability = getMenuAvailability();
+  if (!availability.available) throw new SparkError(availability.reason === "unsupported-platform" ? "E_UNSUPPORTED_PLATFORM" : "E_MODULE_UNAVAILABLE", "Application menus are unavailable");
 }
-export function clearMenus(ownerId: string) {
-  if (Platform.OS === "windows") { const next = new Map(windowsOwners); next.delete(ownerId); publishWindowsMenus(next); }
-  else if (Platform.OS === "macos") NativeMenu.clearMenus(ownerId);
+function snapshot(value: MenuUpdate, token: string, creating = false): MenuWireItem[] {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new SparkError("E_INVALID_ARGUMENT", "Expected menu options");
+  for (const key of Object.keys(value)) if (!["items", ...(creating ? ["id", "onAction"] : [])].includes(key)) throw new SparkError("E_UNSUPPORTED_OPTION", `Unsupported menu option: ${key}`);
+  const items = menuItems(value.items, { types: Platform.OS === "macos" ? ["action", "checkbox", "separator", "submenu", "role"] : ["action", "checkbox", "separator", "submenu"], shortcuts: true, targeting: true, icons: Platform.OS === "macos" ? ["symbol", "image"] : [] }, Platform.OS === "windows" ? "windows" : "macos");
+  if (items.some(item => !item.items)) throw new SparkError("E_INVALID_ARGUMENT", "Application menu roots must be submenus");
+  function annotate(items: MenuWireItem[]) { for (const item of items) { item._sparkOwner = token; if (item.items) annotate(item.items); } }
+  annotate(items); return items;
 }
-export function clearAllMenus() {
-  if (Platform.OS === "windows") { publishWindowsMenus(new Map()); }
-  else if (Platform.OS === "macos") NativeMenu.clearAllMenus();
+async function publish(next: Map<string, Owner>): Promise<void> {
+  const menus = Platform.OS === "windows"
+    ? composeWindowsMenus(new Map([...next].map(([id, owner]) => [id, owner.items])))
+    : [...next.values()].flatMap(owner => owner.items);
+  const result = await invokeNative(() => NativeMenu!.publish(JSON.stringify(menus)));
+  if (result !== undefined && result !== null) throw new SparkError("E_INVALID_DATA", "Native menu publication returned an unexpected result");
+  owners = next;
 }
-
-export function addNativeMenuActionListener(listener: (action: NativeMenuAction) => void) {
-  if ((Platform.OS !== "macos" && Platform.OS !== "windows")) {
-    return { remove() {} };
-  }
-
-  const emitter = new NativeEventEmitter(NativeMenu as never);
-  return emitter.addListener("NativeMenuAction", listener);
-}
-
-export function useNativeMenu({ handlers, menus, onAction, ownerId }: UseNativeMenuOptions) {
-  useEffect(() => {
-    configureMenus(ownerId, menus);
-
-    const subscription = addNativeMenuActionListener((action) => {
-      if (action.ownerId === ownerId) {
-        const handler = handlers?.[action.itemId];
-        if (handler) {
-          handler(action);
-        } else {
-          onAction?.(action);
-        }
-      }
-    });
-
-    return () => {
-      subscription.remove();
-      clearMenus(ownerId);
-    };
-  }, [handlers, menus, onAction, ownerId]);
+export async function createMenu(options: MenuOptions): Promise<Menu> {
+  available();
+  const token = `menu-${Date.now()}-${++sequence}`;
+  const items = snapshot(options, token, true);
+  if (typeof options.id !== "string" || !/^[a-zA-Z0-9_-]{1,100}$/.test(options.id)) throw new SparkError("E_INVALID_ARGUMENT", "Expected a menu owner id");
+  if (options.onAction !== undefined && typeof options.onAction !== "function") throw new SparkError("E_INVALID_ARGUMENT", "Expected onAction callback");
+  const id = options.id, onAction = options.onAction;
+  let stopped = false, ready = false, ids = selectableMenuIds(items);
+  const subscription = new NativeEventEmitter(NativeMenu as never).addListener("NativeMenuAction", event => {
+    if (ready && !stopped && event && event.ownerId === token && typeof event.itemId === "string" && ids.has(event.itemId)) {
+      // All owners share this emitter; one owner's throw must not swallow the other owners' actions.
+      try { onAction?.({ type: "action", itemId: event.itemId }); }
+      catch (cause) { console.error(new SparkError("E_NATIVE", "Menu action handler failed", { cause })); }
+    }
+  });
+  try { await serial(async () => {
+    if (owners.has(id)) throw new SparkError("E_ALREADY_EXISTS", `Menu owner ${id} already exists`);
+    const next = new Map(owners); next.set(id, { id, token, items }); await publish(next); ready = true;
+  }); } catch (error) { subscription.remove(); throw error; }
+  const registration = asyncRegistration(() => { stopped = true; subscription.remove(); }, () => serial(async () => {
+    if (owners.get(id)?.token !== token) return;
+    const next = new Map(owners); next.delete(id); await publish(next);
+  }));
+  return {
+    id,
+    async update(options) {
+      if (stopped) throw new SparkError("E_CLOSED", "Menu was removed");
+      const items = snapshot(options, token);
+      await serial(async () => {
+        // Callers commonly rebuild identical item literals each render; republishing the whole
+        // bar would rebuild native menus for no visible change. Compare the wire trees first.
+        const existing = owners.get(id);
+        if (existing?.token === token && JSON.stringify(existing.items) === JSON.stringify(items)) return;
+        const next = new Map(owners); next.delete(id); next.set(id, { id, token, items });
+        await publish(next); ids = selectableMenuIds(items);
+      });
+    },
+    remove: registration.remove,
+  };
 }
-
-export { default as NativeMenu } from "./NativeMenu";
+export { useMenu, type MenuState, type UseMenuOptions } from "./hooks";

package/vendor/node_modules/@legendapp/spark-native-menu/src/hooks.ts

@@ -0,0 +1,97 @@
+import { useEffect, useLayoutEffect, useRef, useState } from "react";
+import { createMenu, type Menu, type MenuOptions, type MenuAction } from "./api";
+export interface UseMenuOptions extends MenuOptions { onError?: (error: unknown) => void; onCleanupError?: (error: unknown, menu: Menu) => void }
+export type MenuState = { status: "loading" } | { status: "ready"; menu: Menu } | { status: "error"; error: unknown };
+interface Lifetime { menu?: Menu; removing?: Promise<void>; blocker?: Lifetime; items: MenuOptions["items"]; disposed: boolean; completion: Promise<void> }
+const lifetimes = new Map<string, Lifetime>();
+/** Callback changes do not recreate native menus. Structural updates use the same handle. */
+export function useMenu(options: UseMenuOptions): MenuState {
+  const [state, setState] = useState<MenuState>({ status: "loading" });
+  const callbacks = useRef(options);
+  useLayoutEffect(() => { callbacks.current = options; });
+  const current = useRef<Lifetime | undefined>(undefined);
+  useEffect(() => {
+    const previous = lifetimes.get(options.id);
+    let end!: () => void;
+    const ended = new Promise<void>(resolve => { end = resolve; });
+    const owner: Lifetime = { items: options.items, disposed: false, completion: Promise.resolve(), blocker: previous?.disposed ? previous.blocker ?? previous : undefined };
+    current.current = owner; setState({ status: "loading" });
+    const report = (error: unknown) => {
+      if (!owner.disposed) setState({ status: "error", error });
+      try {
+        if (callbacks.current.onError) callbacks.current.onError(error);
+        else console.error("Menu lifecycle failed", error);
+      } catch (callbackError) { console.error(callbackError); }
+    };
+    const remove = (target: Lifetime) => {
+      const menu = target.menu;
+      if (!menu) return Promise.resolve();
+      if (!target.removing) target.removing = menu.remove().then(() => {
+        if (target.menu === menu) target.menu = undefined;
+        if (lifetimes.get(options.id) === target) lifetimes.delete(options.id);
+      }).catch(error => {
+        if (!owner.disposed) setState({ status: "error", error });
+        try {
+          if (callbacks.current.onCleanupError) callbacks.current.onCleanupError(error, menu);
+          else {
+            console.error("Menu cleanup failed; menu handle remains retryable", error, menu);
+            report(error);
+          }
+        } catch (callbackError) { console.error(callbackError); }
+        throw error;
+      }).finally(() => { target.removing = undefined; });
+      return target.removing;
+    };
+    if (!previous || previous.disposed) lifetimes.set(options.id, owner);
+    owner.completion = Promise.resolve().then(async () => {
+      // A remount waits for allocation/disposal, then retries a retained failed removal.
+      if (previous?.disposed) {
+        await previous.completion.catch(() => {});
+        const blocked = owner.blocker;
+        if (blocked) {
+          await blocked.completion.catch(() => {});
+          try { if (blocked.menu) await remove(blocked); }
+          catch { return; }
+          owner.blocker = undefined;
+        }
+      }
+      if (owner.disposed) {
+        if (lifetimes.get(options.id) === owner) lifetimes.delete(options.id);
+        return;
+      }
+      const initial = owner.items;
+      let menu: Menu;
+      try {
+        menu = await createMenu({ id: options.id, items: initial, onAction: (event: MenuAction) => { if (!owner.disposed) callbacks.current.onAction?.(event); } });
+        owner.menu = menu;
+      } catch (error) {
+        report(error);
+        if (lifetimes.get(options.id) === owner) lifetimes.delete(options.id);
+        return;
+      }
+      try {
+        if (!owner.disposed && owner.items !== initial) await menu.update({ items: owner.items });
+        if (!owner.disposed) setState({ status: "ready", menu });
+      } catch (error) { report(error); }
+      await ended;
+      if (owner.disposed) await remove(owner).catch(() => {});
+    }).catch(report);
+    return () => { owner.disposed = true; end(); };
+  }, [options.id]);
+  useEffect(() => {
+    const owner = current.current;
+    if (!owner || owner.disposed || owner.items === options.items) return;
+    owner.items = options.items;
+    if (owner.menu) void owner.menu.update({ items: options.items }).then(() => {
+      // Reusing the previous state keeps an identical-content update from cascading renders.
+      if (!owner.disposed) setState(state => state.status === "ready" && state.menu === owner.menu ? state : { status: "ready", menu: owner.menu! });
+    }).catch(error => {
+      if (!owner.disposed) setState({ status: "error", error });
+      try {
+        if (callbacks.current.onError) callbacks.current.onError(error);
+        else console.error("Menu update failed", error);
+      } catch (callbackError) { console.error(callbackError); }
+    });
+  }, [options.id, options.items]);
+  return state;
+}

package/vendor/node_modules/@legendapp/spark-native-menu/src/windows-menus.ts

@@ -1,43 +1,49 @@
-import type { NativeMenuConfig, NativeMenuItem, NativeMenuItemPatch } from "./api";
-type Item = NativeMenuItem & { _sparkOwner: string; _sparkMenu: string };
-type Menu = Omit<NativeMenuConfig, "items"> & { items: Item[] };
-const titleKey = (title = "") => title.replaceAll("…", "...").trim().toLowerCase();
-function insertion<T extends { title?: string }>(items: T[], placement?: { before?: string; after?: string }) {
-  for (const position of ["before", "after"] as const) {
-    const title = placement?.[position];
-    if (title) { const index = items.findIndex(item => titleKey(item.title) === titleKey(title)); if (index >= 0) return index + (position === "after" ? 1 : 0); }
+import { SparkError } from "@legendapp/spark-desktop-app/src/contracts";
+import type { MenuTarget, MenuWireItem } from "@legendapp/spark-desktop-app/src/contracts/menu";
+function matches(item: MenuWireItem, target: MenuTarget): boolean {
+  return "id" in target ? (item._sparkIdentity ?? item.id) === target.id : "role" in target ? item.role === target.role : !!item.target && "menu" in item.target && item.target.menu === target.menu;
+}
+function insertion(items: MenuWireItem[], placement?: MenuWireItem["placement"]): number {
+  if (!placement) return items.length;
+  const target = placement.before ?? placement.after!;
+  const index = items.findIndex(item => matches(item, target));
+  if (index < 0) throw new SparkError("E_NOT_FOUND", "Menu placement target was not found");
+  return index + (placement.after ? 1 : 0);
+}
+function locate(items: MenuWireItem[], target: MenuTarget, recursive: boolean): { items: MenuWireItem[]; item: MenuWireItem } | undefined {
+  for (const item of items) {
+    if (matches(item, target)) return { items, item };
+    if (recursive && item.items) { const found = locate(item.items, target, true); if (found) return found; }
   }
-  return items.length;
 }
-/** Recompute owners' contributions so removing a binding restores the original item. */
-export type MenuDiagnostic = { code: "E_MENU_TARGET_NOT_FOUND"; ownerId: string; menuId: string; itemId: string; targets: string[] };
-export function composeWindowsMenus(owners: ReadonlyMap<string, NativeMenuConfig[]>, diagnose: (diagnostic: MenuDiagnostic) => void = diagnostic => console.warn("Windows menu target not found", diagnostic)): Menu[] {
-  const result: Menu[] = [];
-  for (const [owner, configs] of owners) for (const config of configs) {
-    let menu = result.find(menu => config.systemMenu === "app" ? menu.systemMenu === "app" : menu.title === config.title);
-    if (!menu) {
-      menu = { ...config, items: [] };
-      result.splice(config.systemMenu === "app" ? 0 : insertion(result, config.placement), 0, menu);
-    }
-    for (const input of config.items) {
-      // Public menu contributions are flat on Windows; AppKit system submenus
-      // have no counterpart. Reject before publishing rather than dropping them.
-      if ((input.targetPath?.length ?? 0) > 1) throw Object.assign(new Error(`Windows menu ${config.id}/${input.id} does not support nested targetPath: ${input.targetPath!.join(" > ")}`), { code: "E_MENU_TARGET_UNSUPPORTED" });
-      const candidates = input.targetPath?.length ? input.targetPath : [input.targetTitle, ...(input.targetTitles ?? [])].filter((title): title is string => !!title);
-      const targets = !!(input.targetTitle || input.targetTitles?.length || input.targetPath?.length);
-      const target = candidates.map(title => menu.items.find(item => titleKey(item.title) === titleKey(title))).find(Boolean);
-      if (targets && !target) { diagnose({ code: "E_MENU_TARGET_NOT_FOUND", ownerId: owner, menuId: config.id, itemId: input.id, targets: candidates }); continue; }
-      const identity = input.targetPath?.length && target ? { _sparkOwner: target._sparkOwner, _sparkMenu: target._sparkMenu, id: target.id, payload: target.payload } : { _sparkOwner: owner, _sparkMenu: config.id, id: input.id };
-      const item: Item = { ...target, ...input, ...identity };
-      if (target) {
-        const index = menu.items.indexOf(target);
-        menu.items.splice(index, 1);
-        menu.items.splice(input.placement ? insertion(menu.items, input.placement) : index, 0, item);
-      } else menu.items.splice(insertion(menu.items, input.placement), 0, item);
+/** Compose fresh snapshots by stable IDs/semantic targets; failed proposals never mutate live owners. */
+export function composeWindowsMenus(owners: ReadonlyMap<string, readonly MenuWireItem[]>): MenuWireItem[] {
+  const result: MenuWireItem[] = [];
+  function merge(into: MenuWireItem[], inputs: readonly MenuWireItem[], root: boolean) {
+    for (const input of inputs) {
+      const found = input.target || input.id ? locate(into, input.target ?? { id: input.id! }, !!input.target && !root) : undefined;
+      const target = found?.item, siblings = found?.items ?? into;
+      if (input.target && !target && !(root && "menu" in input.target)) throw new SparkError("E_NOT_FOUND", `Menu target for ${input.id} was not found`);
+      if (target && input.items) {
+        if (!target.items) throw new SparkError("E_INVALID_ARGUMENT", "Submenu target is not a submenu");
+        const { items: children, id, target: identity, placement, ...presentation } = input;
+        Object.assign(target, presentation);
+        merge(target.items, children, false);
+        if (placement) {
+          const old = siblings.indexOf(target), position = insertion(siblings, placement);
+          siblings.splice(old, 1); siblings.splice(position - (old < position ? 1 : 0), 0, target);
+        }
+      } else {
+        // Overlays keep the owner identity and the role AppKit would retain, so later placements still resolve semantic anchors.
+        const item = { ...input, ...(target ? { _sparkIdentity: target._sparkIdentity ?? target.id } : {}), ...(target?.role && !input.role ? { role: target.role } : {}), ...(input.items ? { items: [] as MenuWireItem[] } : {}) };
+        if (input.items) merge(item.items!, input.items, false);
+        const index = target ? siblings.indexOf(target) : -1;
+        const position = input.placement ? insertion(siblings, input.placement) : index < 0 ? siblings.length : index;
+        if (index >= 0) siblings.splice(index, 1);
+        siblings.splice(position - (index >= 0 && index < position ? 1 : 0), 0, item);
+      }
     }
   }
+  for (const items of owners.values()) merge(result, items, true);
   return result;
 }
-export function patchWindowsMenus(menus: NativeMenuConfig[], patches: NativeMenuItemPatch[]): NativeMenuConfig[] {
-  return menus.map(menu => ({ ...menu, items: menu.items.map(item => patches.reduce((item, patch) => patch.id === item.id ? { ...item, ...patch } : item, item)) }));
-}

package/vendor/node_modules/@legendapp/spark-notifications/macos/RNDesktopNotifications.mm

@@ -16,25 +16,41 @@ static NSString *Identifier(NSString *value) { return [NSString stringWithFormat
 static BOOL Owns(UNNotificationRequest *request) { return [request.content.userInfo[NamespaceKey] isEqual:SparkNamespace()]; }
 @interface SparkNotificationCenter : NSObject <UNUserNotificationCenterDelegate>
 @property NSMutableArray *responses;
+@property NSMutableSet<UNNotificationCategory *> *categories;
+@property BOOL categoriesReady;
+@property NSMutableArray<void (^)(void)> *pendingCategories;
 @property (weak) id<UNUserNotificationCenterDelegate> previous;
 + (instancetype)shared;
+- (void)whenCategoriesReady:(void (^)(void))operation;
 @end
 @implementation SparkNotificationCenter
 + (instancetype)shared {
   static SparkNotificationCenter *instance;
   static dispatch_once_t once;
   dispatch_once(&once, ^{
-    instance = [SparkNotificationCenter new]; instance.responses = [NSMutableArray new];
+    instance = [SparkNotificationCenter new]; instance.responses = [NSMutableArray new]; instance.categories = [NSMutableSet new];
+    instance.pendingCategories = [NSMutableArray new];
     UNUserNotificationCenter *center = UNUserNotificationCenter.currentNotificationCenter;
     instance.previous = center.delegate; center.delegate = instance;
+    // Merge the host categories before publishing any Spark notification.
     [center getNotificationCategoriesWithCompletionHandler:^(NSSet<UNNotificationCategory *> *categories) {
-      NSMutableSet *combined = [categories mutableCopy];
-      [combined addObject:[UNNotificationCategory categoryWithIdentifier:@"spark.desktop.default" actions:@[] intentIdentifiers:@[] options:UNNotificationCategoryOptionCustomDismissAction]];
-      [center setNotificationCategories:combined];
+      dispatch_async(dispatch_get_main_queue(), ^{
+        [instance.categories addObjectsFromArray:categories.allObjects];
+        [instance.categories addObject:[UNNotificationCategory categoryWithIdentifier:@"spark.desktop.default" actions:@[] intentIdentifiers:@[] options:UNNotificationCategoryOptionCustomDismissAction]];
+        [center setNotificationCategories:[instance.categories copy]];
+        instance.categoriesReady = YES;
+        NSArray<void (^)(void)> *pending = [instance.pendingCategories copy];
+        [instance.pendingCategories removeAllObjects];
+        for (void (^operation)(void) in pending) operation();
+      });
     }];
   });
   return instance;
 }
+- (void)whenCategoriesReady:(void (^)(void))operation {
+  if (self.categoriesReady) operation();
+  else [self.pendingCategories addObject:[operation copy]];
+}
 + (void)load {
   // Install before launch finishes, including when a notification launches the app.
   [NSNotificationCenter.defaultCenter addObserverForName:NSApplicationWillFinishLaunchingNotification object:nil queue:NSOperationQueue.mainQueue usingBlock:^(NSNotification *note) { [self shared]; }];
@@ -51,9 +67,12 @@ static BOOL Owns(UNNotificationRequest *request) { return [request.content.userI
     return;
   }
   NSDictionary *info = response.notification.request.content.userInfo;
+  NSString *action = @"open";
+  if ([response.actionIdentifier isEqual:UNNotificationDismissActionIdentifier]) action = @"dismiss";
+  else if ([response.actionIdentifier hasPrefix:@"spark.action."]) action = [response.actionIdentifier substringFromIndex:@"spark.action.".length];
   NSDictionary *event = @{ @"type": @"notificationResponse", @"id": NSUUID.UUID.UUIDString,
     @"notificationId": info[@"sparkId"] ?: @"", @"data": info[@"sparkData"] ?: @{},
-    @"action": [response.actionIdentifier isEqual:UNNotificationDismissActionIdentifier] ? @"dismiss" : @"open" };
+    @"action": action };
   dispatch_async(dispatch_get_main_queue(), ^{
     [self.responses addObject:event]; if (self.responses.count > 100) [self.responses removeObjectAtIndex:0];
     SparkEmit(event); completion();
@@ -74,34 +93,60 @@ RCT_EXPORT_MODULE(NativeDesktopNotifications)
       if ([method isEqual:@"permission"]) read();
       else [center requestAuthorizationWithOptions:UNAuthorizationOptionAlert | UNAuthorizationOptionSound completionHandler:^(BOOL granted, NSError *error) { if (error) SparkReject(reject, error); else read(); }];
     } else if ([method isEqual:@"show"]) {
-      if (![args[@"id"] isKindOfClass:NSString.class] || ![args[@"title"] isKindOfClass:NSString.class]) { SparkInvalid(reject, @"Notification needs an id and title"); return; }
-      UNMutableNotificationContent *content = [UNMutableNotificationContent new];
-      content.categoryIdentifier = @"spark.desktop.default";
-      content.title = args[@"title"]; content.body = args[@"body"] ?: @""; content.subtitle = args[@"subtitle"] ?: @"";
-      if ([args[@"sound"] boolValue]) content.sound = UNNotificationSound.defaultSound;
-      content.userInfo = @{ NamespaceKey: SparkNamespace(), @"sparkId": args[@"id"], @"sparkData": args[@"data"] ?: @{} };
-      UNNotificationTrigger *trigger = args[@"delay"] ? [UNTimeIntervalNotificationTrigger triggerWithTimeInterval:[args[@"delay"] doubleValue] repeats:NO] : nil;
-      UNNotificationRequest *request = [UNNotificationRequest requestWithIdentifier:Identifier(args[@"id"]) content:content trigger:trigger];
-      [center getNotificationSettingsWithCompletionHandler:^(UNNotificationSettings *settings) {
-        if (settings.authorizationStatus != UNAuthorizationStatusAuthorized && settings.authorizationStatus != UNAuthorizationStatusProvisional) { reject(@"E_NOTIFICATION_PERMISSION", @"Request notification permission from a user action before showing notifications", nil); return; }
-        [center addNotificationRequest:request withCompletionHandler:^(NSError *error) { if (error) SparkReject(reject, error); else resolve(@"null"); }];
+      [delegate whenCategoriesReady:^{
+        if (![args[@"id"] isKindOfClass:NSString.class] || ![args[@"title"] isKindOfClass:NSString.class]) { SparkInvalid(reject, @"Notification needs an id and title"); return; }
+        UNMutableNotificationContent *content = [UNMutableNotificationContent new];
+        NSArray *actions = [args[@"actions"] isKindOfClass:NSArray.class] ? args[@"actions"] : nil;
+        content.title = args[@"title"]; content.body = args[@"body"] ?: @""; content.subtitle = args[@"subtitle"] ?: @"";
+        // JS normalizes sound to "none", "default", or a tone name. macOS user
+        // notification sounds must ship in the app bundle or Library/Sounds, so
+        // tones present the platform default here; Windows maps tones to system sounds.
+        NSString *sound = [args[@"sound"] isKindOfClass:NSString.class] ? args[@"sound"] : nil;
+        if (sound.length > 0 && ![sound isEqual:@"none"]) content.sound = UNNotificationSound.defaultSound;
+        content.categoryIdentifier = @"spark.desktop.default";
+        if (actions.count > 0) {
+          // Categories are app-global; namespace identifiers so Spark registrations
+          // never collide with a host app's own UNNotificationCategory set.
+          NSMutableArray<UNNotificationAction *> *categoryActions = [NSMutableArray new];
+          NSMutableString *signature = [NSMutableString stringWithString:@"spark.actions."];
+          for (NSDictionary *action in actions) {
+            if (![action[@"id"] isKindOfClass:NSString.class] || ![action[@"label"] isKindOfClass:NSString.class]) { SparkInvalid(reject, @"Notification actions need an id and label"); return; }
+            [categoryActions addObject:[UNNotificationAction actionWithIdentifier:[@"spark.action." stringByAppendingString:action[@"id"]] title:action[@"label"] options:UNNotificationActionOptionNone]];
+            [signature appendFormat:@"%@:%@|", action[@"id"], action[@"label"]];
+          }
+          content.categoryIdentifier = signature;
+          UNNotificationCategory *category = [UNNotificationCategory categoryWithIdentifier:signature actions:categoryActions intentIdentifiers:@[] options:UNNotificationCategoryOptionCustomDismissAction];
+          if (![delegate.categories containsObject:category]) {
+            [delegate.categories addObject:category];
+            [center setNotificationCategories:[delegate.categories copy]];
+          }
+        }
+        content.userInfo = @{ NamespaceKey: SparkNamespace(), @"sparkId": args[@"id"], @"sparkData": args[@"data"] ?: @{} };
+        UNNotificationTrigger *trigger = args[@"delay"] ? [UNTimeIntervalNotificationTrigger triggerWithTimeInterval:[args[@"delay"] doubleValue] repeats:NO] : nil;
+        UNNotificationRequest *request = [UNNotificationRequest requestWithIdentifier:Identifier(args[@"id"]) content:content trigger:trigger];
+        [center getNotificationSettingsWithCompletionHandler:^(UNNotificationSettings *settings) {
+          if (settings.authorizationStatus != UNAuthorizationStatusAuthorized && settings.authorizationStatus != UNAuthorizationStatusProvisional) { reject(@"E_PERMISSION_DENIED", @"Request notification permission from a user action before showing notifications", nil); return; }
+          [center addNotificationRequest:request withCompletionHandler:^(NSError *error) { if (error) SparkReject(reject, error); else resolve(@"null"); }];
+        }];
       }];
-    } else if ([method isEqual:@"cancel"]) {
-      [center removePendingNotificationRequestsWithIdentifiers:@[Identifier(args[@"id"])]];
-      [center removeDeliveredNotificationsWithIdentifiers:@[Identifier(args[@"id"])]]; resolve(@"null");
-    } else if ([method isEqual:@"pending"] || [method isEqual:@"delivered"] || [method isEqual:@"clear"]) {
-      BOOL clear = [method isEqual:@"clear"];
-      if ([method isEqual:@"pending"] || clear) [center getPendingNotificationRequestsWithCompletionHandler:^(NSArray<UNNotificationRequest *> *requests) {
-        NSMutableArray *ids = [NSMutableArray new]; NSMutableArray *nativeIds = [NSMutableArray new];
+    } else if ([method isEqual:@"cancel"] || [method isEqual:@"dismiss"]) {
+      NSArray *ids = @[Identifier(args[@"id"])];
+      if ([method isEqual:@"cancel"]) [center removePendingNotificationRequestsWithIdentifiers:ids];
+      else [center removeDeliveredNotificationsWithIdentifiers:ids];
+      resolve(@"null");
+    } else if ([method isEqual:@"pending"] || [method isEqual:@"cancelAll"]) {
+      [center getPendingNotificationRequestsWithCompletionHandler:^(NSArray<UNNotificationRequest *> *requests) {
+        NSMutableArray *ids = [NSMutableArray new], *nativeIds = [NSMutableArray new];
         for (UNNotificationRequest *request in requests) if (Owns(request)) { [ids addObject:request.content.userInfo[@"sparkId"]]; [nativeIds addObject:request.identifier]; }
-        if (clear) [center removePendingNotificationRequestsWithIdentifiers:nativeIds]; else resolve(SparkJSON(ids));
-        if (clear) [center getDeliveredNotificationsWithCompletionHandler:^(NSArray<UNNotification *> *notifications) {
-          NSMutableArray *delivered = [NSMutableArray new]; for (UNNotification *notification in notifications) if (Owns(notification.request)) [delivered addObject:notification.request.identifier];
-          [center removeDeliveredNotificationsWithIdentifiers:delivered]; resolve(@"null");
-        }];
+        if ([method isEqual:@"cancelAll"]) { [center removePendingNotificationRequestsWithIdentifiers:nativeIds]; resolve(@"null"); }
+        else resolve(SparkJSON(ids));
       }];
-      else [center getDeliveredNotificationsWithCompletionHandler:^(NSArray<UNNotification *> *notifications) {
-        NSMutableArray *ids = [NSMutableArray new]; for (UNNotification *notification in notifications) if (Owns(notification.request)) [ids addObject:notification.request.content.userInfo[@"sparkId"]]; resolve(SparkJSON(ids));
+    } else if ([method isEqual:@"delivered"] || [method isEqual:@"dismissAll"]) {
+      [center getDeliveredNotificationsWithCompletionHandler:^(NSArray<UNNotification *> *notifications) {
+        NSMutableArray *ids = [NSMutableArray new], *nativeIds = [NSMutableArray new];
+        for (UNNotification *notification in notifications) if (Owns(notification.request)) { [ids addObject:notification.request.content.userInfo[@"sparkId"]]; [nativeIds addObject:notification.request.identifier]; }
+        if ([method isEqual:@"dismissAll"]) { [center removeDeliveredNotificationsWithIdentifiers:nativeIds]; resolve(@"null"); }
+        else resolve(SparkJSON(ids));
       }];
     } else if ([method isEqual:@"responses"]) resolve(SparkJSON([delegate.responses copy]));
     else SparkInvalid(reject, @"Unknown notification operation");