@noego/wood 0.6.0 → 0.6.1

package/dist/main/shutdown_coordinator.d.cts

@@ -0,0 +1,81 @@
+import { Logger } from '@noego/logger';
+
+/**
+ * Bounded time the last renderers get to acknowledge the shutdown drain
+ * (trace transport close + app-registered persistence hooks) before their
+ * windows are destroyed.
+ */
+declare const RENDERER_SHUTDOWN_DRAIN_TIMEOUT_MS = 1000;
+type ShutdownWindow = Readonly<{
+    isDestroyed(): boolean;
+    hide(): void;
+    destroy(): void;
+}>;
+type ShutdownPreventableEvent = Readonly<{
+    preventDefault(): void;
+}>;
+type ShutdownReason = 'last-window-close' | 'quit';
+type ShutdownPhase = 'idle' | 'draining' | 'windows-destroyed' | 'cleaning-backend' | 'complete';
+type ShutdownCoordinatorDependencies = Readonly<{
+    /** Live view of the tracked windows; iterated as a snapshot on each use. */
+    trackedWindows(): Iterable<readonly [string, ShutdownWindow]>;
+    /** Forget every tracked window after destruction. */
+    clearTrackedWindows(): void;
+    /** Bounded renderer drain (traces + persistence acknowledgements). */
+    drainRenderers(): Promise<void>;
+    /** Backend runtime/service teardown; runs only after windows are gone. */
+    cleanupBackend(): Promise<void>;
+    /** Ask Electron to quit; the coordinator calls this exactly once, at the end. */
+    requestQuit(): void;
+    logger: Pick<Logger, 'debug' | 'info' | 'warn'>;
+}>;
+declare function shouldDeferLastWindowCloseForCleanup(trackedWindowCount: number, cleanupComplete: boolean): boolean;
+/**
+ * Owns the Desktop shutdown sequence so windows disappear first and the
+ * backend is torn down last:
+ *
+ *   accepted last-window Close or Quit
+ *     -> hide every tracked window immediately
+ *     -> bounded renderer drain (trace close + persistence acknowledgements)
+ *     -> destroy every tracked window
+ *     -> backend runtime/service cleanup
+ *     -> app.quit()
+ *
+ * The sequence runs exactly once. Every Electron quit attempt that arrives
+ * while it is in flight (repeated Cmd+Q, the `closed` -> `window-all-closed`
+ * cascade caused by our own window destruction, a second Close) is prevented
+ * so the process cannot exit before cleanup finishes. Once complete, the final
+ * `requestQuit()` is allowed through untouched.
+ */
+declare class ShutdownCoordinator {
+    private readonly deps;
+    private currentPhase;
+    private shutdown;
+    constructor(deps: ShutdownCoordinatorDependencies);
+    get phase(): ShutdownPhase;
+    get isActive(): boolean;
+    get isComplete(): boolean;
+    /** Resolves when the in-flight (or already finished) shutdown sequence settles. */
+    whenSettled(): Promise<void>;
+    /**
+     * `close` handler for a tracked BrowserWindow. Returns true when the close
+     * was intercepted (last window, or a shutdown is already running); false
+     * means the window may close normally.
+     */
+    handleTrackedWindowClose(event: ShutdownPreventableEvent, trackedWindowCount: number): boolean;
+    /** `before-quit` handler. Prevents every quit until the sequence completes. */
+    handleBeforeQuit(event: ShutdownPreventableEvent): void;
+    /**
+     * `window-all-closed` / last `closed` handler. While a shutdown is in flight
+     * the coordinator issues the final quit itself, so the cascade caused by
+     * destroying our own windows must not request another one.
+     */
+    handleAllWindowsClosed(): void;
+    private begin;
+    private run;
+    private hideAllWindows;
+    private hideWindow;
+    private destroyAllWindows;
+}
+
+export { RENDERER_SHUTDOWN_DRAIN_TIMEOUT_MS, ShutdownCoordinator, type ShutdownCoordinatorDependencies, type ShutdownPhase, type ShutdownPreventableEvent, type ShutdownReason, type ShutdownWindow, shouldDeferLastWindowCloseForCleanup };

package/dist/main/shutdown_coordinator.d.ts

@@ -0,0 +1,81 @@
+import { Logger } from '@noego/logger';
+
+/**
+ * Bounded time the last renderers get to acknowledge the shutdown drain
+ * (trace transport close + app-registered persistence hooks) before their
+ * windows are destroyed.
+ */
+declare const RENDERER_SHUTDOWN_DRAIN_TIMEOUT_MS = 1000;
+type ShutdownWindow = Readonly<{
+    isDestroyed(): boolean;
+    hide(): void;
+    destroy(): void;
+}>;
+type ShutdownPreventableEvent = Readonly<{
+    preventDefault(): void;
+}>;
+type ShutdownReason = 'last-window-close' | 'quit';
+type ShutdownPhase = 'idle' | 'draining' | 'windows-destroyed' | 'cleaning-backend' | 'complete';
+type ShutdownCoordinatorDependencies = Readonly<{
+    /** Live view of the tracked windows; iterated as a snapshot on each use. */
+    trackedWindows(): Iterable<readonly [string, ShutdownWindow]>;
+    /** Forget every tracked window after destruction. */
+    clearTrackedWindows(): void;
+    /** Bounded renderer drain (traces + persistence acknowledgements). */
+    drainRenderers(): Promise<void>;
+    /** Backend runtime/service teardown; runs only after windows are gone. */
+    cleanupBackend(): Promise<void>;
+    /** Ask Electron to quit; the coordinator calls this exactly once, at the end. */
+    requestQuit(): void;
+    logger: Pick<Logger, 'debug' | 'info' | 'warn'>;
+}>;
+declare function shouldDeferLastWindowCloseForCleanup(trackedWindowCount: number, cleanupComplete: boolean): boolean;
+/**
+ * Owns the Desktop shutdown sequence so windows disappear first and the
+ * backend is torn down last:
+ *
+ *   accepted last-window Close or Quit
+ *     -> hide every tracked window immediately
+ *     -> bounded renderer drain (trace close + persistence acknowledgements)
+ *     -> destroy every tracked window
+ *     -> backend runtime/service cleanup
+ *     -> app.quit()
+ *
+ * The sequence runs exactly once. Every Electron quit attempt that arrives
+ * while it is in flight (repeated Cmd+Q, the `closed` -> `window-all-closed`
+ * cascade caused by our own window destruction, a second Close) is prevented
+ * so the process cannot exit before cleanup finishes. Once complete, the final
+ * `requestQuit()` is allowed through untouched.
+ */
+declare class ShutdownCoordinator {
+    private readonly deps;
+    private currentPhase;
+    private shutdown;
+    constructor(deps: ShutdownCoordinatorDependencies);
+    get phase(): ShutdownPhase;
+    get isActive(): boolean;
+    get isComplete(): boolean;
+    /** Resolves when the in-flight (or already finished) shutdown sequence settles. */
+    whenSettled(): Promise<void>;
+    /**
+     * `close` handler for a tracked BrowserWindow. Returns true when the close
+     * was intercepted (last window, or a shutdown is already running); false
+     * means the window may close normally.
+     */
+    handleTrackedWindowClose(event: ShutdownPreventableEvent, trackedWindowCount: number): boolean;
+    /** `before-quit` handler. Prevents every quit until the sequence completes. */
+    handleBeforeQuit(event: ShutdownPreventableEvent): void;
+    /**
+     * `window-all-closed` / last `closed` handler. While a shutdown is in flight
+     * the coordinator issues the final quit itself, so the cascade caused by
+     * destroying our own windows must not request another one.
+     */
+    handleAllWindowsClosed(): void;
+    private begin;
+    private run;
+    private hideAllWindows;
+    private hideWindow;
+    private destroyAllWindows;
+}
+
+export { RENDERER_SHUTDOWN_DRAIN_TIMEOUT_MS, ShutdownCoordinator, type ShutdownCoordinatorDependencies, type ShutdownPhase, type ShutdownPreventableEvent, type ShutdownReason, type ShutdownWindow, shouldDeferLastWindowCloseForCleanup };

package/dist/main/shutdown_coordinator.js

@@ -0,0 +1,127 @@
+const RENDERER_SHUTDOWN_DRAIN_TIMEOUT_MS = 1e3;
+function shouldDeferLastWindowCloseForCleanup(trackedWindowCount, cleanupComplete) {
+  return trackedWindowCount === 1 && !cleanupComplete;
+}
+class ShutdownCoordinator {
+  constructor(deps) {
+    this.deps = deps;
+    this.currentPhase = "idle";
+    this.shutdown = null;
+  }
+  get phase() {
+    return this.currentPhase;
+  }
+  get isActive() {
+    return this.shutdown !== null;
+  }
+  get isComplete() {
+    return this.currentPhase === "complete";
+  }
+  /** Resolves when the in-flight (or already finished) shutdown sequence settles. */
+  whenSettled() {
+    return this.shutdown ?? Promise.resolve();
+  }
+  /**
+   * `close` handler for a tracked BrowserWindow. Returns true when the close
+   * was intercepted (last window, or a shutdown is already running); false
+   * means the window may close normally.
+   */
+  handleTrackedWindowClose(event, trackedWindowCount) {
+    if (this.isComplete) {
+      return false;
+    }
+    if (this.shutdown) {
+      event.preventDefault();
+      return true;
+    }
+    if (!shouldDeferLastWindowCloseForCleanup(trackedWindowCount, false)) {
+      return false;
+    }
+    event.preventDefault();
+    this.begin("last-window-close");
+    return true;
+  }
+  /** `before-quit` handler. Prevents every quit until the sequence completes. */
+  handleBeforeQuit(event) {
+    if (this.isComplete) {
+      return;
+    }
+    event.preventDefault();
+    if (this.shutdown) {
+      return;
+    }
+    this.begin("quit");
+  }
+  /**
+   * `window-all-closed` / last `closed` handler. While a shutdown is in flight
+   * the coordinator issues the final quit itself, so the cascade caused by
+   * destroying our own windows must not request another one.
+   */
+  handleAllWindowsClosed() {
+    if (this.shutdown) {
+      return;
+    }
+    this.deps.requestQuit();
+  }
+  begin(reason) {
+    this.deps.logger.info("shutdown started", { reason });
+    this.shutdown = this.run();
+  }
+  async run() {
+    this.hideAllWindows();
+    this.currentPhase = "draining";
+    try {
+      await this.deps.drainRenderers();
+    } catch (error) {
+      this.deps.logger.warn("renderer shutdown drain failed", { error: toErrorMessage(error) });
+    }
+    this.destroyAllWindows();
+    this.currentPhase = "windows-destroyed";
+    this.currentPhase = "cleaning-backend";
+    try {
+      await this.deps.cleanupBackend();
+    } catch (error) {
+      this.deps.logger.warn("backend shutdown cleanup failed", { error: toErrorMessage(error) });
+    }
+    this.currentPhase = "complete";
+    this.deps.logger.info("shutdown complete");
+    this.deps.requestQuit();
+  }
+  hideAllWindows() {
+    for (const [id, window] of [...this.deps.trackedWindows()]) {
+      this.hideWindow(id, window);
+    }
+  }
+  hideWindow(id, window) {
+    try {
+      if (!window.isDestroyed()) {
+        window.hide();
+        this.deps.logger.debug("hid window for shutdown", { windowId: id });
+      }
+    } catch (error) {
+      this.deps.logger.warn("hiding window for shutdown failed", { windowId: id, error: toErrorMessage(error) });
+    }
+  }
+  destroyAllWindows() {
+    for (const [id, window] of [...this.deps.trackedWindows()]) {
+      try {
+        if (!window.isDestroyed()) {
+          window.destroy();
+          this.deps.logger.debug("destroyed window on shutdown", { windowId: id });
+        }
+      } catch (error) {
+        this.deps.logger.warn("destroying window on shutdown failed", { windowId: id, error: toErrorMessage(error) });
+      }
+    }
+    this.deps.clearTrackedWindows();
+  }
+}
+function toErrorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+export {
+  RENDERER_SHUTDOWN_DRAIN_TIMEOUT_MS,
+  ShutdownCoordinator,
+  shouldDeferLastWindowCloseForCleanup
+};
+//# sourceMappingURL=shutdown_coordinator.js.map

package/dist/main/shutdown_coordinator.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/main/shutdown_coordinator.ts"],"sourcesContent":["import type { Logger } from '@noego/logger';\n\n/**\n * Bounded time the last renderers get to acknowledge the shutdown drain\n * (trace transport close + app-registered persistence hooks) before their\n * windows are destroyed.\n */\nexport const RENDERER_SHUTDOWN_DRAIN_TIMEOUT_MS = 1_000;\n\nexport type ShutdownWindow = Readonly<{\n  isDestroyed(): boolean;\n  hide(): void;\n  destroy(): void;\n}>;\n\nexport type ShutdownPreventableEvent = Readonly<{\n  preventDefault(): void;\n}>;\n\nexport type ShutdownReason = 'last-window-close' | 'quit';\n\nexport type ShutdownPhase =\n  | 'idle'\n  | 'draining'\n  | 'windows-destroyed'\n  | 'cleaning-backend'\n  | 'complete';\n\nexport type ShutdownCoordinatorDependencies = Readonly<{\n  /** Live view of the tracked windows; iterated as a snapshot on each use. */\n  trackedWindows(): Iterable<readonly [string, ShutdownWindow]>;\n  /** Forget every tracked window after destruction. */\n  clearTrackedWindows(): void;\n  /** Bounded renderer drain (traces + persistence acknowledgements). */\n  drainRenderers(): Promise<void>;\n  /** Backend runtime/service teardown; runs only after windows are gone. */\n  cleanupBackend(): Promise<void>;\n  /** Ask Electron to quit; the coordinator calls this exactly once, at the end. */\n  requestQuit(): void;\n  logger: Pick<Logger, 'debug' | 'info' | 'warn'>;\n}>;\n\nexport function shouldDeferLastWindowCloseForCleanup(\n  trackedWindowCount: number,\n  cleanupComplete: boolean,\n): boolean {\n  return trackedWindowCount === 1 && !cleanupComplete;\n}\n\n/**\n * Owns the Desktop shutdown sequence so windows disappear first and the\n * backend is torn down last:\n *\n *   accepted last-window Close or Quit\n *     -> hide every tracked window immediately\n *     -> bounded renderer drain (trace close + persistence acknowledgements)\n *     -> destroy every tracked window\n *     -> backend runtime/service cleanup\n *     -> app.quit()\n *\n * The sequence runs exactly once. Every Electron quit attempt that arrives\n * while it is in flight (repeated Cmd+Q, the `closed` -> `window-all-closed`\n * cascade caused by our own window destruction, a second Close) is prevented\n * so the process cannot exit before cleanup finishes. Once complete, the final\n * `requestQuit()` is allowed through untouched.\n */\nexport class ShutdownCoordinator {\n  private currentPhase: ShutdownPhase = 'idle';\n  private shutdown: Promise<void> | null = null;\n\n  constructor(private readonly deps: ShutdownCoordinatorDependencies) {}\n\n  get phase(): ShutdownPhase {\n    return this.currentPhase;\n  }\n\n  get isActive(): boolean {\n    return this.shutdown !== null;\n  }\n\n  get isComplete(): boolean {\n    return this.currentPhase === 'complete';\n  }\n\n  /** Resolves when the in-flight (or already finished) shutdown sequence settles. */\n  whenSettled(): Promise<void> {\n    return this.shutdown ?? Promise.resolve();\n  }\n\n  /**\n   * `close` handler for a tracked BrowserWindow. Returns true when the close\n   * was intercepted (last window, or a shutdown is already running); false\n   * means the window may close normally.\n   */\n  handleTrackedWindowClose(\n    event: ShutdownPreventableEvent,\n    trackedWindowCount: number,\n  ): boolean {\n    if (this.isComplete) {\n      return false;\n    }\n    if (this.shutdown) {\n      // Shutdown owns window destruction; do not let a competing close race it.\n      event.preventDefault();\n      return true;\n    }\n    if (!shouldDeferLastWindowCloseForCleanup(trackedWindowCount, false)) {\n      return false;\n    }\n    event.preventDefault();\n    // begin() hides every tracked window synchronously, including this one.\n    this.begin('last-window-close');\n    return true;\n  }\n\n  /** `before-quit` handler. Prevents every quit until the sequence completes. */\n  handleBeforeQuit(event: ShutdownPreventableEvent): void {\n    if (this.isComplete) {\n      return;\n    }\n    event.preventDefault();\n    if (this.shutdown) {\n      return;\n    }\n    this.begin('quit');\n  }\n\n  /**\n   * `window-all-closed` / last `closed` handler. While a shutdown is in flight\n   * the coordinator issues the final quit itself, so the cascade caused by\n   * destroying our own windows must not request another one.\n   */\n  handleAllWindowsClosed(): void {\n    if (this.shutdown) {\n      return;\n    }\n    this.deps.requestQuit();\n  }\n\n  private begin(reason: ShutdownReason): void {\n    this.deps.logger.info('shutdown started', { reason });\n    this.shutdown = this.run();\n  }\n\n  private async run(): Promise<void> {\n    this.hideAllWindows();\n\n    this.currentPhase = 'draining';\n    try {\n      await this.deps.drainRenderers();\n    } catch (error) {\n      this.deps.logger.warn('renderer shutdown drain failed', { error: toErrorMessage(error) });\n    }\n\n    this.destroyAllWindows();\n    this.currentPhase = 'windows-destroyed';\n\n    this.currentPhase = 'cleaning-backend';\n    try {\n      await this.deps.cleanupBackend();\n    } catch (error) {\n      this.deps.logger.warn('backend shutdown cleanup failed', { error: toErrorMessage(error) });\n    }\n\n    this.currentPhase = 'complete';\n    this.deps.logger.info('shutdown complete');\n    this.deps.requestQuit();\n  }\n\n  private hideAllWindows(): void {\n    for (const [id, window] of [...this.deps.trackedWindows()]) {\n      this.hideWindow(id, window);\n    }\n  }\n\n  private hideWindow(id: string, window: ShutdownWindow): void {\n    try {\n      if (!window.isDestroyed()) {\n        window.hide();\n        this.deps.logger.debug('hid window for shutdown', { windowId: id });\n      }\n    } catch (error) {\n      this.deps.logger.warn('hiding window for shutdown failed', { windowId: id, error: toErrorMessage(error) });\n    }\n  }\n\n  private destroyAllWindows(): void {\n    for (const [id, window] of [...this.deps.trackedWindows()]) {\n      try {\n        if (!window.isDestroyed()) {\n          window.destroy();\n          this.deps.logger.debug('destroyed window on shutdown', { windowId: id });\n        }\n      } catch (error) {\n        this.deps.logger.warn('destroying window on shutdown failed', { windowId: id, error: toErrorMessage(error) });\n      }\n    }\n    this.deps.clearTrackedWindows();\n  }\n}\n\nfunction toErrorMessage(error: unknown): string {\n  return error instanceof Error ? error.message : String(error);\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noego/wood",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",