@adea-ai/app-framework 0.27.0 → 0.28.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (125) hide show
  1. package/README.md +177 -15
  2. package/dist/app/create-application.d.ts +2 -0
  3. package/dist/app/create-application.js +6 -0
  4. package/dist/app/service-registry.js +4 -0
  5. package/dist/appearance/custom-theme-import.js +43 -7
  6. package/dist/appearance/custom-theme-library.d.ts +2 -0
  7. package/dist/appearance/custom-theme-library.js +5 -1
  8. package/dist/appearance/theme-record-adapter.js +4 -2
  9. package/dist/appearance/theme-registry.js +7 -1
  10. package/dist/cli/cli-runner.d.ts +4 -0
  11. package/dist/cli/cli-runner.js +14 -1
  12. package/dist/cli/create-application-cli.js +4 -2
  13. package/dist/cli/release-cut-cli.js +2 -2
  14. package/dist/cli/update-helper-cli.js +28 -6
  15. package/dist/desktop/client-asset-manifest.d.ts +47 -0
  16. package/dist/desktop/client-asset-manifest.js +114 -0
  17. package/dist/desktop/client-asset-stream.d.ts +10 -0
  18. package/dist/desktop/client-asset-stream.js +138 -33
  19. package/dist/desktop/client-assets.d.ts +20 -0
  20. package/dist/desktop/client-assets.js +132 -22
  21. package/dist/desktop/client-response-lifecycle.d.ts +22 -0
  22. package/dist/desktop/client-response-lifecycle.js +233 -0
  23. package/dist/desktop/desktop-host.d.ts +40 -2
  24. package/dist/desktop/desktop-host.js +159 -9
  25. package/dist/framework-source.json +1 -1
  26. package/dist/installer/command-artifact.d.ts +4 -2
  27. package/dist/installer/command-artifact.js +119 -19
  28. package/dist/installer/linux-process-group.d.ts +13 -0
  29. package/dist/installer/linux-process-group.js +58 -0
  30. package/dist/native/darwin-sync.d.ts +7 -0
  31. package/dist/native/darwin-sync.js +43 -0
  32. package/dist/native/desktop-build-hook.js +7 -0
  33. package/dist/native/directory-exchange.d.ts +10 -0
  34. package/dist/native/directory-exchange.js +90 -0
  35. package/dist/native/electrobun-source-patch.d.ts +5 -0
  36. package/dist/native/electrobun-source-patch.js +19 -1
  37. package/dist/native/posix-launcher-build.d.ts +24 -0
  38. package/dist/native/posix-launcher-build.js +232 -0
  39. package/dist/native/posix-tree-removal.d.ts +36 -0
  40. package/dist/native/posix-tree-removal.js +425 -0
  41. package/dist/release/feed-release-cut.js +30 -10
  42. package/dist/release/github-release-cut.js +16 -0
  43. package/dist/release/release-cut.d.ts +8 -1
  44. package/dist/release/release-cut.js +9 -1
  45. package/dist/update-helper.bundle.js +1483 -105
  46. package/dist/updates/channel-update-manager.d.ts +5 -0
  47. package/dist/updates/channel-update-manager.js +13 -1
  48. package/dist/updates/desktop-updater.d.ts +78 -2
  49. package/dist/updates/desktop-updater.js +320 -37
  50. package/dist/updates/launch-environment.d.ts +2 -0
  51. package/dist/updates/launch-environment.js +4 -0
  52. package/dist/updates/native-file-lock.d.ts +15 -0
  53. package/dist/updates/native-file-lock.js +189 -0
  54. package/dist/updates/packaged-launch-admission.d.ts +13 -0
  55. package/dist/updates/packaged-launch-admission.js +45 -0
  56. package/dist/updates/packaged-release-config.d.ts +18 -0
  57. package/dist/updates/packaged-release-config.js +60 -0
  58. package/dist/updates/packaged-update-startup.d.ts +44 -0
  59. package/dist/updates/packaged-update-startup.js +81 -0
  60. package/dist/updates/update-arm.d.ts +9 -8
  61. package/dist/updates/update-arm.js +227 -62
  62. package/dist/updates/update-cleanup-error.d.ts +23 -0
  63. package/dist/updates/update-cleanup-error.js +65 -0
  64. package/dist/updates/update-download-cleanup.d.ts +11 -0
  65. package/dist/updates/update-download-cleanup.js +112 -2
  66. package/dist/updates/update-download-lock.d.ts +20 -0
  67. package/dist/updates/update-download-lock.js +73 -0
  68. package/dist/updates/update-download.d.ts +2 -0
  69. package/dist/updates/update-download.js +7 -3
  70. package/dist/updates/update-generation-lease.d.ts +6 -0
  71. package/dist/updates/update-generation-lease.js +14 -0
  72. package/dist/updates/update-helper.d.ts +11 -2
  73. package/dist/updates/update-helper.js +322 -13
  74. package/dist/updates/update-inherited-launch-lease.d.ts +22 -0
  75. package/dist/updates/update-inherited-launch-lease.js +58 -0
  76. package/dist/updates/update-instance-lease.d.ts +15 -0
  77. package/dist/updates/update-instance-lease.js +25 -0
  78. package/dist/updates/update-launch-gate.d.ts +137 -0
  79. package/dist/updates/update-launch-gate.js +617 -0
  80. package/dist/updates/update-launch.js +3 -1
  81. package/dist/updates/update-lock.d.ts +12 -0
  82. package/dist/updates/update-lock.js +18 -0
  83. package/dist/updates/update-manager.d.ts +2 -0
  84. package/dist/updates/update-manager.js +9 -2
  85. package/dist/updates/update-marker.d.ts +7 -0
  86. package/dist/updates/update-marker.js +62 -0
  87. package/dist/updates/update-preflight-error.d.ts +7 -0
  88. package/dist/updates/update-preflight-error.js +11 -0
  89. package/dist/updates/update-process-fence.d.ts +4 -0
  90. package/dist/updates/update-process-fence.js +85 -73
  91. package/dist/updates/update-process-liveness.d.ts +2 -0
  92. package/dist/updates/update-process-liveness.js +11 -0
  93. package/dist/updates/update-resume.d.ts +37 -3
  94. package/dist/updates/update-resume.js +839 -23
  95. package/dist/updates/update-retention-marker.d.ts +67 -0
  96. package/dist/updates/update-retention-marker.js +165 -0
  97. package/dist/updates/update-retention-plan.d.ts +25 -0
  98. package/dist/updates/update-retention-plan.js +54 -0
  99. package/dist/updates/update-retention-sync.d.ts +34 -0
  100. package/dist/updates/update-retention-sync.js +83 -0
  101. package/dist/updates/update-retirement.d.ts +205 -0
  102. package/dist/updates/update-retirement.js +1485 -0
  103. package/dist/updates/update-shutdown.d.ts +16 -4
  104. package/dist/updates/update-shutdown.js +133 -8
  105. package/dist/updates/update-state-store.d.ts +58 -0
  106. package/dist/updates/update-state-store.js +139 -0
  107. package/dist/updates/update-swap-stage.d.ts +1 -1
  108. package/dist/updates/update-swap-stage.js +85 -14
  109. package/dist/updates/update-swap.d.ts +45 -2
  110. package/dist/updates/update-swap.js +207 -17
  111. package/package.json +31 -1
  112. package/src/appearance/custom-theme-import.ts +96 -14
  113. package/src/appearance/custom-theme-library.ts +5 -0
  114. package/src/appearance/theme-record-adapter.ts +15 -6
  115. package/src/appearance/theme-registry.ts +8 -1
  116. package/src/desktop/client-asset-manifest.ts +207 -0
  117. package/src/desktop/client-asset-stream.ts +193 -32
  118. package/src/desktop/client-assets.ts +210 -19
  119. package/src/desktop/client-response-lifecycle.ts +305 -0
  120. package/src/native/electrobun-posix-launch-lease.patch +398 -0
  121. package/templates/application/README.md +50 -0
  122. package/templates/application/electrobun.config.ts +5 -1
  123. package/templates/application/scripts/build-desktop.ts +4 -0
  124. package/templates/application/src/bun/index.ts +173 -16
  125. package/templates/application/vite.config.ts +112 -6
@@ -0,0 +1,233 @@
1
+ // src/desktop/client-response-lifecycle.ts
2
+ /** A request was admitted after the response lifecycle had started draining. */
3
+ var ClientResponseLifecycleClosedError = class extends Error {
4
+ constructor() {
5
+ super("Client response lifecycle is closed");
6
+ this.name = "ClientResponseLifecycleClosedError";
7
+ }
8
+ };
9
+ async function cancelClientResponse(response, reason) {
10
+ const body = response.body;
11
+ if (!body) return;
12
+ if (body.locked || response.bodyUsed) throw new Error("Cannot safely cancel an untracked client response body");
13
+ await body.cancel(reason);
14
+ }
15
+ /**
16
+ * Tracks async asset handlers and the response bodies they create. The response
17
+ * body returned from `handle` remains owned by its caller for normal reads; this
18
+ * tracker keeps a reader so shutdown can cancel it even while the body is locked
19
+ * by the host's response writer.
20
+ */
21
+ function createClientResponseLifecycleTracker() {
22
+ let accepting = true;
23
+ let drain;
24
+ const handlers = /* @__PURE__ */ new Set();
25
+ const bodies = /* @__PURE__ */ new Set();
26
+ const cleanupFailures = [];
27
+ let stopped = false;
28
+ const rememberFailure = (error) => {
29
+ cleanupFailures.push(error);
30
+ };
31
+ const trackBody = (source) => {
32
+ const reader = source.getReader();
33
+ const pendingReads = /* @__PURE__ */ new Set();
34
+ const pendingPulls = /* @__PURE__ */ new Set();
35
+ let controller;
36
+ let terminal = false;
37
+ let sourceClosed = false;
38
+ let sourceFailureRecorded = false;
39
+ let cancelRequested = false;
40
+ let cancelTask;
41
+ let cancelSettled = false;
42
+ let settleBody;
43
+ const settled = new Promise((resolve) => {
44
+ settleBody = resolve;
45
+ });
46
+ const settleIfReady = () => {
47
+ if (terminal && pendingReads.size === 0 && pendingPulls.size === 0 && (!cancelRequested || cancelSettled)) {
48
+ bodies.delete(body);
49
+ settleBody();
50
+ }
51
+ };
52
+ const closeAfterPendingPulls = () => {
53
+ if (sourceClosed && pendingReads.size === 0 && pendingPulls.size === 0) closeOutput();
54
+ };
55
+ const closeOutput = () => {
56
+ if (terminal) return;
57
+ terminal = true;
58
+ try {
59
+ controller?.close();
60
+ } catch {}
61
+ settleIfReady();
62
+ };
63
+ const errorOutput = (error) => {
64
+ if (terminal) return;
65
+ if (!sourceFailureRecorded) {
66
+ sourceFailureRecorded = true;
67
+ rememberFailure(error);
68
+ }
69
+ terminal = true;
70
+ try {
71
+ controller?.error(error);
72
+ } catch {}
73
+ settleIfReady();
74
+ };
75
+ const cancel = (reason) => {
76
+ if (cancelTask) return cancelTask;
77
+ if (terminal) return settled;
78
+ cancelRequested = true;
79
+ try {
80
+ controller?.close();
81
+ } catch {}
82
+ let operation;
83
+ try {
84
+ operation = reader.cancel(reason);
85
+ } catch (error) {
86
+ operation = Promise.reject(error);
87
+ }
88
+ cancelTask = operation.then(() => {}, (error) => {
89
+ rememberFailure(error);
90
+ throw error;
91
+ }).finally(() => {
92
+ cancelSettled = true;
93
+ terminal = true;
94
+ settleIfReady();
95
+ });
96
+ return cancelTask;
97
+ };
98
+ const body = {
99
+ cancel,
100
+ settled
101
+ };
102
+ bodies.add(body);
103
+ const output = new ReadableStream({
104
+ start(value) {
105
+ controller = value;
106
+ },
107
+ pull(value) {
108
+ if (terminal || cancelRequested) return;
109
+ let operation;
110
+ operation = Promise.resolve().then(async () => {
111
+ let read;
112
+ try {
113
+ read = reader.read();
114
+ pendingReads.add(read);
115
+ const result = await read;
116
+ if (cancelRequested || terminal) return;
117
+ if (result.done) {
118
+ sourceClosed = true;
119
+ closeOutput();
120
+ return;
121
+ }
122
+ value.enqueue(result.value);
123
+ } catch (error) {
124
+ if (!cancelRequested) errorOutput(error);
125
+ } finally {
126
+ if (read) pendingReads.delete(read);
127
+ pendingPulls.delete(operation);
128
+ closeAfterPendingPulls();
129
+ settleIfReady();
130
+ }
131
+ });
132
+ pendingPulls.add(operation);
133
+ return operation;
134
+ },
135
+ cancel(reason) {
136
+ return cancel(reason);
137
+ }
138
+ }, { highWaterMark: 0 });
139
+ reader.closed.then(() => {
140
+ if (!cancelRequested) {
141
+ sourceClosed = true;
142
+ closeAfterPendingPulls();
143
+ }
144
+ }, (error) => {
145
+ if (!cancelRequested) errorOutput(error);
146
+ });
147
+ return {
148
+ ...body,
149
+ stream: output
150
+ };
151
+ };
152
+ const handle = (factory) => {
153
+ if (!accepting) return Promise.reject(new ClientResponseLifecycleClosedError());
154
+ let releaseHandler;
155
+ const handler = new Promise((resolve) => {
156
+ releaseHandler = resolve;
157
+ });
158
+ handlers.add(handler);
159
+ return (async () => {
160
+ try {
161
+ const response = await factory();
162
+ if (!(response instanceof Response)) throw new TypeError("Asset handler did not return a Response");
163
+ if (!accepting) {
164
+ try {
165
+ await cancelClientResponse(response, new ClientResponseLifecycleClosedError());
166
+ } catch (error) {
167
+ rememberFailure(error);
168
+ throw error;
169
+ }
170
+ throw new ClientResponseLifecycleClosedError();
171
+ }
172
+ if (!response.body) return response;
173
+ if (response.body.locked || response.bodyUsed) {
174
+ const error = /* @__PURE__ */ new Error("Cannot track a locked or consumed client response body");
175
+ rememberFailure(error);
176
+ throw error;
177
+ }
178
+ const tracked = trackBody(response.body);
179
+ try {
180
+ return new Response(tracked.stream, {
181
+ status: response.status,
182
+ statusText: response.statusText,
183
+ headers: response.headers
184
+ });
185
+ } catch (error) {
186
+ rememberFailure(error);
187
+ throw error;
188
+ }
189
+ } finally {
190
+ handlers.delete(handler);
191
+ releaseHandler();
192
+ }
193
+ })();
194
+ };
195
+ const quiesce = () => {
196
+ if (stopped) return Promise.reject(new ClientResponseLifecycleClosedError());
197
+ accepting = false;
198
+ return Promise.all([...handlers, ...[...bodies].map((body) => body.settled)]).then(() => {});
199
+ };
200
+ const resume = () => {
201
+ if (stopped) throw new ClientResponseLifecycleClosedError();
202
+ accepting = true;
203
+ };
204
+ const stopAndDrain = (reason = new ClientResponseLifecycleClosedError()) => {
205
+ accepting = false;
206
+ if (drain) return drain;
207
+ stopped = true;
208
+ const pendingHandlers = [...handlers];
209
+ const pendingBodies = [...bodies];
210
+ const cancellations = pendingBodies.map((body) => body.cancel(reason));
211
+ drain = (async () => {
212
+ const failures = (await Promise.allSettled([
213
+ ...pendingHandlers,
214
+ ...pendingBodies.map((body) => body.settled),
215
+ ...cancellations
216
+ ])).flatMap((result) => result.status === "rejected" ? [result.reason] : []);
217
+ failures.push(...cleanupFailures);
218
+ const uniqueFailures = [...new Set(failures)];
219
+ if (uniqueFailures.length > 0) throw new AggregateError(uniqueFailures, "Client response cleanup failed");
220
+ })();
221
+ return drain;
222
+ };
223
+ return {
224
+ handle,
225
+ quiesce,
226
+ resume,
227
+ stopAndDrain,
228
+ get accepting() {
229
+ return accepting;
230
+ }
231
+ };
232
+ }
233
+ export { ClientResponseLifecycleClosedError, createClientResponseLifecycleTracker };
@@ -1,13 +1,18 @@
1
+ import { type RetainedClientAssetRoot } from './client-assets';
1
2
  import { type NativeWindow, type SecureWindowOptions } from '../native/secure-window';
2
3
  import type { DesktopRenderer } from '../native/renderer-profile';
3
4
  import type { WindowFrame } from '../native/window-options';
4
5
  import type { createServiceRegistry } from '../app/service-registry';
5
6
  import { createDesktopStreams } from './desktop-stream';
6
7
  /** Bind an isolated client server and open a window with a per-window channel. */
7
- export declare function startDesktopHost<Principal, Window extends NativeWindow>(options: {
8
+ type DesktopHostOptions<Principal, Window extends NativeWindow> = {
8
9
  clientRoot: string;
9
10
  /** Stream only when the client root is immutable; defaults to buffered snapshots. */
10
11
  streamClientAssets?: boolean;
12
+ /** Explicit content-verified cache allowlist; omitted assets and HTML stay no-store. */
13
+ immutableClientAssets?: ReadonlyMap<string, string>;
14
+ /** Caller-owned roots kept immutable and available until host responses finish. */
15
+ retainedClientAssets?: readonly RetainedClientAssetRoot[];
11
16
  /** Existing app-owned file or new path for a stable loopback origin. */
12
17
  portFile?: string;
13
18
  /** Preserve an existing loopback origin when creating the port file. */
@@ -39,12 +44,44 @@ export declare function startDesktopHost<Principal, Window extends NativeWindow>
39
44
  origin: 'matching' | 'missing' | 'opaque' | 'same-host' | 'other';
40
45
  fetchSite: string | null;
41
46
  }) => void;
42
- }): {
47
+ };
48
+ export declare function startDesktopHost<Principal, Window extends NativeWindow>(options: DesktopHostOptions<Principal, Window>): {
43
49
  origin: string;
44
50
  window: Window;
45
51
  stop: () => void;
46
52
  revokeChannels: () => void;
47
53
  };
54
+ /**
55
+ * Transfer a retained-root lease to the host. The roots supplied in options must
56
+ * be covered by the lease. Shutdown cancels and drains client responses before
57
+ * releasing it. A failed drain keeps the lease held. Await `close()` to observe
58
+ * shutdown and release errors, including after a native window closes itself.
59
+ * Ownership transfers on entry, including when startup fails.
60
+ */
61
+ export declare function startDesktopHostWithRetainedLease<Principal, Window extends NativeWindow>(options: DesktopHostOptions<Principal, Window>, lease: {
62
+ release(): Promise<void>;
63
+ }, retry?: {
64
+ timeoutMs?: number;
65
+ intervalMs?: number;
66
+ }): Promise<{
67
+ origin: string;
68
+ window: Window;
69
+ stop: () => void;
70
+ revokeChannels: () => void;
71
+ /**
72
+ * Temporarily stop client-asset admission and await existing handlers and
73
+ * bodies without canceling them. On timeout, keep admission paused until
74
+ * the caller has canceled its update helper and calls
75
+ * `resumeClientAssetsAfterCancelledShutdown()`.
76
+ */
77
+ quiesceClientAssets(timeoutMs: number): Promise<void>;
78
+ /**
79
+ * Resume only after helper cancellation is confirmed. A concurrently
80
+ * stopped host stays terminal and its finalizer retains lease ownership.
81
+ */
82
+ resumeClientAssetsAfterCancelledShutdown(): void;
83
+ close(): Promise<void>;
84
+ }>;
48
85
  /** Retry only a failed loopback bind while the previous process exits. */
49
86
  export declare function startDesktopHostWithRetry<Principal, Window extends NativeWindow>(options: Parameters<typeof startDesktopHost<Principal, Window>>[0], retry?: {
50
87
  timeoutMs?: number;
@@ -55,3 +92,4 @@ export declare function startDesktopHostWithRetry<Principal, Window extends Nati
55
92
  stop: () => void;
56
93
  revokeChannels: () => void;
57
94
  }>;
95
+ export {};
@@ -1,5 +1,7 @@
1
1
  import { createChannelAuthority } from "./channel-handshake.js";
2
- import { serveClient } from "./client-assets.js";
2
+ import { createClientAssetVerificationCache } from "./client-asset-stream.js";
3
+ import { createClientAssetResolver } from "./client-assets.js";
4
+ import { ClientResponseLifecycleClosedError, createClientResponseLifecycleTracker } from "./client-response-lifecycle.js";
3
5
  import { createLoopbackPolicy, matchesLoopbackOrigin } from "./loopback-policy.js";
4
6
  import { isValidGatewayTimeoutMs } from "./gateway-limits.js";
5
7
  import { createDesktopGateway } from "./desktop-gateway.js";
@@ -16,8 +18,10 @@ var DesktopPortInUseError = class extends Error {
16
18
  super("Desktop origin port is in use", { cause });
17
19
  }
18
20
  };
19
- /** Bind an isolated client server and open a window with a per-window channel. */
20
21
  function startDesktopHost(options) {
22
+ return createDesktopHost(options);
23
+ }
24
+ function createDesktopHost(options, lifecycle) {
21
25
  const reportRequest = (...args) => {
22
26
  try {
23
27
  const result = options.onRequest?.(...args);
@@ -27,6 +31,13 @@ function startDesktopHost(options) {
27
31
  const dispatchTimeoutMs = options.dispatchTimeoutMs;
28
32
  if (!isValidGatewayTimeoutMs(dispatchTimeoutMs)) throw new Error("Invalid gateway limits");
29
33
  if (options.streamClientAssets !== void 0 && typeof options.streamClientAssets !== "boolean") throw new Error("Invalid desktop client asset policy");
34
+ const clientAssetVerificationCache = createClientAssetVerificationCache();
35
+ const serveAssets = createClientAssetResolver({
36
+ root: options.clientRoot,
37
+ streamAssets: options.streamClientAssets,
38
+ immutableAssets: options.immutableClientAssets,
39
+ verificationCache: clientAssetVerificationCache
40
+ }, options.retainedClientAssets);
30
41
  const configuredRoutes = options.routes ?? [];
31
42
  if (!Array.isArray(configuredRoutes) || configuredRoutes.length > 32 || configuredRoutes.some((route) => !route || typeof route.prefix !== "string" || !/^\/[a-zA-Z0-9][a-zA-Z0-9._-]*(?:\/[a-zA-Z0-9][a-zA-Z0-9._-]*)*$/.test(route.prefix) || route.prefix.length > 200 || route.prefix === "/__framework" || route.prefix.startsWith("/__framework/") || typeof route.handle !== "function") || configuredRoutes.some((route, index) => configuredRoutes.slice(index + 1).some((other) => route.prefix === other.prefix || route.prefix.startsWith(other.prefix + "/") || other.prefix.startsWith(route.prefix + "/")))) throw new Error("Invalid desktop route policy");
32
43
  const routes = configuredRoutes.map(({ prefix, handle }) => ({
@@ -61,7 +72,7 @@ function startDesktopHost(options) {
61
72
  hostname: "127.0.0.1",
62
73
  port,
63
74
  async fetch(request, connection) {
64
- if (!origin || !gateway) return new Response(null, { status: 503 });
75
+ if (stopped || !origin || !gateway) return new Response(null, { status: 503 });
65
76
  const url = new URL(request.url);
66
77
  if (url.origin !== origin || request.headers.get("host") !== new URL(origin).host) {
67
78
  reportRequest("rejected");
@@ -104,10 +115,13 @@ function startDesktopHost(options) {
104
115
  }
105
116
  }
106
117
  reportRequest(kind);
107
- const result = await serveClient(request, {
108
- root: options.clientRoot,
109
- streamAssets: options.streamClientAssets
110
- });
118
+ let result;
119
+ try {
120
+ result = lifecycle ? await lifecycle.tracker.handle(() => serveAssets(request)) : await serveAssets(request);
121
+ } catch (error) {
122
+ if (error instanceof ClientResponseLifecycleClosedError) return new Response(null, { status: 503 });
123
+ throw error;
124
+ }
111
125
  result.headers.set("content-security-policy", "frame-src 'none'; frame-ancestors 'none'; object-src 'none'; base-uri 'none'");
112
126
  result.headers.set("x-content-type-options", "nosniff");
113
127
  result.headers.set("referrer-policy", "no-referrer");
@@ -139,6 +153,7 @@ function startDesktopHost(options) {
139
153
  const cleanupResources = (throwCleanupError) => {
140
154
  if (stopped) return;
141
155
  stopped = true;
156
+ lifecycle?.onStop();
142
157
  let cleanupFailed = false;
143
158
  let cleanupError;
144
159
  for (const cleanup of [
@@ -152,6 +167,7 @@ function startDesktopHost(options) {
152
167
  if (!cleanupFailed) cleanupError = error;
153
168
  cleanupFailed = true;
154
169
  }
170
+ if (cleanupFailed) lifecycle?.onCleanupFailure(cleanupError);
155
171
  if (throwCleanupError && cleanupFailed) throw cleanupError;
156
172
  };
157
173
  const stop = () => cleanupResources(true);
@@ -202,16 +218,150 @@ function startDesktopHost(options) {
202
218
  throw error;
203
219
  }
204
220
  }
221
+ /**
222
+ * Transfer a retained-root lease to the host. The roots supplied in options must
223
+ * be covered by the lease. Shutdown cancels and drains client responses before
224
+ * releasing it. A failed drain keeps the lease held. Await `close()` to observe
225
+ * shutdown and release errors, including after a native window closes itself.
226
+ * Ownership transfers on entry, including when startup fails.
227
+ */
228
+ async function startDesktopHostWithRetainedLease(options, lease, retry) {
229
+ const tracker = createClientResponseLifecycleTracker();
230
+ const release = lease.release.bind(lease);
231
+ let finalizing;
232
+ let cleanupFailed = false;
233
+ let cleanupFailure;
234
+ let shutdownState = "active";
235
+ let signalStopped;
236
+ const stoppedSignal = new Promise((resolve) => {
237
+ signalStopped = resolve;
238
+ });
239
+ const onCleanupFailure = (error) => {
240
+ cleanupFailed = true;
241
+ cleanupFailure = error;
242
+ };
243
+ const currentShutdownState = () => shutdownState;
244
+ const finalize = () => finalizing ??= tracker.stopAndDrain().then(() => release());
245
+ const onStop = () => {
246
+ shutdownState = "stopping";
247
+ signalStopped();
248
+ finalize().then(() => {
249
+ shutdownState = "stopped";
250
+ }, () => {
251
+ shutdownState = "stopped";
252
+ });
253
+ };
254
+ let host;
255
+ try {
256
+ host = retry ? await retryDesktopHost(() => createDesktopHost(options, {
257
+ tracker,
258
+ onStop,
259
+ onCleanupFailure
260
+ }), retry) : createDesktopHost(options, {
261
+ tracker,
262
+ onStop,
263
+ onCleanupFailure
264
+ });
265
+ } catch (error) {
266
+ try {
267
+ await finalize();
268
+ } catch (cleanupError) {
269
+ throw new AggregateError(cleanupFailed ? [
270
+ error,
271
+ cleanupFailure,
272
+ cleanupError
273
+ ] : [error, cleanupError], "Desktop startup and lease cleanup failed", { cause: cleanupError });
274
+ }
275
+ if (cleanupFailed) throw new AggregateError([error, cleanupFailure], "Desktop startup and shutdown failed", { cause: error });
276
+ throw error;
277
+ }
278
+ return {
279
+ ...host,
280
+ /**
281
+ * Temporarily stop client-asset admission and await existing handlers and
282
+ * bodies without canceling them. On timeout, keep admission paused until
283
+ * the caller has canceled its update helper and calls
284
+ * `resumeClientAssetsAfterCancelledShutdown()`.
285
+ */
286
+ async quiesceClientAssets(timeoutMs) {
287
+ if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 12e4) throw new Error("Invalid client asset quiescence timeout");
288
+ if (shutdownState !== "active") throw new Error("Desktop host is not available to quiesce");
289
+ shutdownState = "quiescing";
290
+ const drained = tracker.quiesce();
291
+ let timer;
292
+ try {
293
+ if (await Promise.race([
294
+ drained.then(() => "drained"),
295
+ stoppedSignal.then(() => "stopped"),
296
+ new Promise((_, reject) => {
297
+ timer = setTimeout(() => {
298
+ if (shutdownState === "stopping" || shutdownState === "stopped") return;
299
+ reject(/* @__PURE__ */ new Error("Desktop client assets did not quiesce before shutdown"));
300
+ }, timeoutMs);
301
+ })
302
+ ]) === "stopped") return;
303
+ } finally {
304
+ if (timer) clearTimeout(timer);
305
+ }
306
+ const stateAfterQuiescence = currentShutdownState();
307
+ if (stateAfterQuiescence === "stopping" || stateAfterQuiescence === "stopped") return;
308
+ if (stateAfterQuiescence !== "quiescing") throw new Error("Desktop host cannot finish quiescing");
309
+ shutdownState = "quiesced";
310
+ },
311
+ /**
312
+ * Resume only after helper cancellation is confirmed. A concurrently
313
+ * stopped host stays terminal and its finalizer retains lease ownership.
314
+ */
315
+ resumeClientAssetsAfterCancelledShutdown() {
316
+ if (shutdownState === "active") return;
317
+ if (shutdownState === "stopping" || shutdownState === "stopped") return;
318
+ if (shutdownState !== "quiescing" && shutdownState !== "quiesced") throw new Error("Desktop host cannot resume after shutdown started");
319
+ tracker.resume();
320
+ shutdownState = "active";
321
+ },
322
+ async close() {
323
+ let stopFailed = false;
324
+ let stopError;
325
+ shutdownState = "stopping";
326
+ try {
327
+ host.stop();
328
+ } catch (error) {
329
+ stopFailed = true;
330
+ stopError = error;
331
+ }
332
+ try {
333
+ await finalize();
334
+ } catch (error) {
335
+ shutdownState = "stopped";
336
+ if (cleanupFailed) {
337
+ stopFailed = true;
338
+ stopError = cleanupFailure;
339
+ }
340
+ if (stopFailed) throw new AggregateError([stopError, error], "Desktop shutdown and lease cleanup failed", { cause: error });
341
+ throw error;
342
+ }
343
+ shutdownState = "stopped";
344
+ if (cleanupFailed) {
345
+ stopFailed = true;
346
+ stopError = cleanupFailure;
347
+ }
348
+ if (stopFailed) throw stopError;
349
+ }
350
+ };
351
+ }
205
352
  /** Retry only a failed loopback bind while the previous process exits. */
206
353
  async function startDesktopHostWithRetry(options, retry = {}) {
354
+ return retryDesktopHost(() => startDesktopHost(options), retry);
355
+ }
356
+ async function retryDesktopHost(start, retry) {
207
357
  const timeoutMs = retry.timeoutMs ?? 3e4, intervalMs = retry.intervalMs ?? 250;
208
358
  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 12e4 || !Number.isSafeInteger(intervalMs) || intervalMs < 1 || intervalMs > 5e3) throw new Error("Invalid desktop bind retry policy");
209
359
  const deadline = performance.now() + timeoutMs;
210
360
  for (;;) try {
211
- return startDesktopHost(options);
361
+ return start();
212
362
  } catch (error) {
213
363
  if (!(error instanceof DesktopPortInUseError) || performance.now() >= deadline) throw error;
214
364
  await Bun.sleep(Math.min(intervalMs, Math.max(1, deadline - performance.now())));
215
365
  }
216
366
  }
217
- export { startDesktopHost, startDesktopHostWithRetry };
367
+ export { startDesktopHost, startDesktopHostWithRetainedLease, startDesktopHostWithRetry };
@@ -1 +1 @@
1
- {"version":"0.27.0","commit":"379422bb8d442fb7182a26a70d9d4f40410e7f6e"}
1
+ {"version":"0.28.1","commit":"9ced256448ba7f6b0d77d359dc5a68157dc34dd7"}
@@ -34,8 +34,10 @@ export type CommandQualification = {
34
34
  /**
35
35
  * Extract the archive into a new private location with its own home and data directories, then
36
36
  * run `--version` (it must print `version`), each probe (each must exit 0), and the service
37
- * (it must stay up through a settle window, then stop on SIGTERM with exit 0; on Windows, where
38
- * no signal reaches a console process, its process tree is terminated).
37
+ * (it must stay up through a settle window, then stop on SIGTERM with exit 0; on POSIX, cleanup
38
+ * covers members of the isolated process group, while descendants that detach from that group
39
+ * can outlive it. Windows normal-path taskkill uses a PID lookup with a check-to-use race and no
40
+ * Job Object ownership; early-exit cleanup only signals the retained direct-child handle).
39
41
  */
40
42
  export declare function qualifyCommandArtifact(options: {
41
43
  archive: string;