@adea-ai/app-framework 0.25.0 → 0.26.0

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 (138) hide show
  1. package/README.md +157 -19
  2. package/dist/app/application.d.ts +11 -4
  3. package/dist/app/application.js +24 -4
  4. package/dist/app/create-application.d.ts +9 -0
  5. package/dist/app/create-application.js +214 -143
  6. package/dist/app/private-group.d.ts +14 -0
  7. package/dist/app/private-group.js +39 -0
  8. package/dist/app/service-registry.d.ts +8 -4
  9. package/dist/app/service-registry.js +43 -6
  10. package/dist/appearance/custom-theme-import.d.ts +5 -7
  11. package/dist/appearance/custom-theme-import.js +66 -18
  12. package/dist/appearance/custom-theme-library.d.ts +51 -3
  13. package/dist/appearance/custom-theme-library.js +262 -33
  14. package/dist/appearance/editor.d.ts +3 -1
  15. package/dist/appearance/editor.js +37 -2
  16. package/dist/appearance/theme-file-importer.d.ts +7 -3
  17. package/dist/appearance/theme-file-importer.js +27 -7
  18. package/dist/appearance/theme-library-action-fence.d.ts +11 -0
  19. package/dist/appearance/theme-library-action-fence.js +29 -0
  20. package/dist/cli/cef-helper-cli.js +0 -0
  21. package/dist/cli/create-application-cli.js +0 -0
  22. package/dist/cli/electrobun-shortcut-patch-cli.js +0 -0
  23. package/dist/cli/framework-update-cli.js +16 -3
  24. package/dist/cli/macos-signing-cli.js +0 -0
  25. package/dist/cli/release-assets-plan-cli.js +0 -0
  26. package/dist/cli/release-cut-cli.js +0 -0
  27. package/dist/cli/release-descriptor-staging-cli.js +0 -0
  28. package/dist/cli/release-finalize-cli.js +0 -0
  29. package/dist/cli/release-promote-cli.js +0 -0
  30. package/dist/cli/release-publish-cli.js +0 -0
  31. package/dist/cli/release-sign-cli.js +0 -0
  32. package/dist/cli/release-step-cli.js +0 -0
  33. package/dist/cli/toolchain-identity-cli.js +0 -0
  34. package/dist/cli/windows-runtime-patch-cli.js +0 -0
  35. package/dist/desktop/application-command-client.d.ts +11 -1
  36. package/dist/desktop/application-command-client.js +66 -3
  37. package/dist/desktop/channel-handshake.d.ts +2 -1
  38. package/dist/desktop/channel-handshake.js +21 -5
  39. package/dist/desktop/client-asset-stream.d.ts +10 -0
  40. package/dist/desktop/client-asset-stream.js +97 -0
  41. package/dist/desktop/client-assets.d.ts +3 -1
  42. package/dist/desktop/client-assets.js +41 -6
  43. package/dist/desktop/desktop-client.d.ts +15 -1
  44. package/dist/desktop/desktop-client.js +235 -109
  45. package/dist/desktop/desktop-gateway.d.ts +2 -0
  46. package/dist/desktop/desktop-gateway.js +134 -22
  47. package/dist/desktop/desktop-host-websocket.d.ts +10 -0
  48. package/dist/desktop/desktop-host-websocket.js +28 -0
  49. package/dist/desktop/desktop-host.d.ts +9 -0
  50. package/dist/desktop/desktop-host.js +70 -61
  51. package/dist/desktop/desktop-port-file.d.ts +2 -0
  52. package/dist/desktop/desktop-port-file.js +23 -0
  53. package/dist/desktop/desktop-stream.d.ts +5 -0
  54. package/dist/desktop/desktop-stream.js +83 -15
  55. package/dist/desktop/gateway-limits.d.ts +2 -0
  56. package/dist/desktop/gateway-limits.js +6 -0
  57. package/dist/desktop/open-url-channel.d.ts +5 -3
  58. package/dist/desktop/open-url-channel.js +18 -5
  59. package/dist/desktop/typed-array-intrinsics.d.ts +6 -0
  60. package/dist/desktop/typed-array-intrinsics.js +19 -0
  61. package/dist/framework-source.json +1 -1
  62. package/dist/installer/installed-payload.js +1 -1
  63. package/dist/installer/installer-ci-bootstrap.js +2 -1
  64. package/dist/installer/installer-command.d.ts +13 -0
  65. package/dist/installer/installer-command.js +47 -0
  66. package/dist/installer/installer-extraction.js +27 -61
  67. package/dist/installer/installer-identity.d.ts +19 -3
  68. package/dist/installer/installer-identity.js +58 -70
  69. package/dist/installer/installer-image-mount.d.ts +48 -0
  70. package/dist/installer/installer-image-mount.js +347 -0
  71. package/dist/installer/installer-layout.js +1 -1
  72. package/dist/installer/installer-process-cleanup.js +1 -1
  73. package/dist/installer/installer-renderer-evidence.js +6 -2
  74. package/dist/installer/upgrade-asset-download.js +30 -8
  75. package/dist/native/app-bundle.d.ts +2 -2
  76. package/dist/native/app-bundle.js +5 -4
  77. package/dist/native/cef-helper-download.d.ts +1 -0
  78. package/dist/native/cef-helper-download.js +35 -0
  79. package/dist/native/cef-helper.js +146 -61
  80. package/dist/native/exclusive-rename.d.ts +2 -0
  81. package/dist/native/exclusive-rename.js +52 -0
  82. package/dist/native/native-secret-store.js +5 -4
  83. package/dist/native/partitioned-window.d.ts +5 -2
  84. package/dist/native/partitioned-window.js +69 -9
  85. package/dist/native/sidecar-services.js +2 -2
  86. package/dist/native/sidecar.js +68 -25
  87. package/dist/native/window-bootstrap.js +2 -2
  88. package/dist/release/feed-state.js +2 -1
  89. package/dist/release/framework-update-lock.d.ts +2 -0
  90. package/dist/release/framework-update-lock.js +42 -0
  91. package/dist/release/framework-update.d.ts +6 -2
  92. package/dist/release/framework-update.js +165 -40
  93. package/dist/release/local-release.js +68 -39
  94. package/dist/release/release-config.js +1 -1
  95. package/dist/shared/discard-stream.d.ts +4 -0
  96. package/dist/shared/discard-stream.js +9 -0
  97. package/dist/shell/app-shell.js +59 -7
  98. package/dist/shell/app-utilities.js +2 -2
  99. package/dist/shell/application-menu.d.ts +13 -0
  100. package/dist/shell/application-menu.js +21 -8
  101. package/dist/update-helper.bundle.js +40 -4
  102. package/dist/updates/channel-update-manager.d.ts +2 -0
  103. package/dist/updates/channel-update-manager.js +15 -3
  104. package/dist/updates/desktop-updater.d.ts +2 -0
  105. package/dist/updates/desktop-updater.js +36 -7
  106. package/dist/updates/linux-process-state.d.ts +2 -0
  107. package/dist/updates/linux-process-state.js +13 -0
  108. package/dist/updates/release-location.js +5 -4
  109. package/dist/updates/update-adapter.js +5 -0
  110. package/dist/updates/update-arm.d.ts +2 -0
  111. package/dist/updates/update-arm.js +58 -7
  112. package/dist/updates/update-discovery.js +2 -1
  113. package/dist/updates/update-download-cleanup.d.ts +7 -0
  114. package/dist/updates/update-download-cleanup.js +21 -0
  115. package/dist/updates/update-download.js +41 -20
  116. package/dist/updates/update-exclusive-rename.d.ts +3 -2
  117. package/dist/updates/update-exclusive-rename.js +3 -50
  118. package/dist/updates/update-extraction.js +1 -1
  119. package/dist/updates/update-manager.d.ts +17 -1
  120. package/dist/updates/update-manager.js +27 -8
  121. package/dist/updates/update-process-fence.js +18 -3
  122. package/dist/views/appearance-surface.js +51 -15
  123. package/package.json +11 -6
  124. package/src/app/application.tsx +49 -7
  125. package/src/appearance/custom-theme-import.ts +67 -7
  126. package/src/appearance/custom-theme-library.ts +391 -33
  127. package/src/appearance/editor.ts +49 -10
  128. package/src/appearance/theme-file-importer.ts +43 -12
  129. package/src/appearance/theme-library-action-fence.ts +28 -0
  130. package/src/desktop/client-asset-stream.ts +118 -0
  131. package/src/desktop/client-assets.ts +55 -5
  132. package/src/shell/app-shell.tsx +71 -8
  133. package/src/shell/app-utilities.tsx +2 -2
  134. package/src/updates/update-adapter.ts +5 -0
  135. package/src/views/appearance-surface.tsx +61 -29
  136. package/templates/application/README.md +5 -1
  137. package/templates/application/scripts/app-version.ts +7 -3
  138. package/templates/application/src/bun/index.ts +2 -0
package/README.md CHANGED
@@ -7,10 +7,16 @@ Each consuming app supplies its identity, navigation, views, services, and
7
7
  application-specific security policy. The [framework contract](docs/framework-contract.md)
8
8
  defines that ownership split and the acceptance gates.
9
9
 
10
- `serveClient(request, { root, deniedPaths, transformHtml })` serves a local SPA,
10
+ `serveClient(request, { root, deniedPaths, transformHtml, streamAssets })` serves a local SPA,
11
11
  rejects paths that escape its root, and lets the app exclude asset trees and
12
12
  inject its bootstrap into HTML. It does not authenticate bridge requests or
13
- start an HTTP server; the host application owns both.
13
+ start an HTTP server; the host application owns both. HEAD responses contain no
14
+ body and report the representation's byte length. HTML transforms still run for
15
+ HEAD requests so their resulting length can be reported.
16
+
17
+ Responses are buffered snapshots by default. Set `streamAssets: true` for an
18
+ immutable asset root, or `streamClientAssets: true` on `startDesktopHost`; streamed
19
+ bodies are not snapshots and read errors can surface after response headers are sent.
14
20
 
15
21
  `serveClient` is one of the framework's desktop building blocks. Source adapted from
16
22
  `adea-ai/adea` at commit `6155d18941acbb14d9099bc2a33a50ee9683a068`,
@@ -85,6 +91,14 @@ The host controls sidebar state and persisted width; the shell restores focus
85
91
  after the narrow-screen sidebar closes and handles the advertised search chord.
86
92
  The narrow-screen drawer loads the first time the window is narrow, so a wide
87
93
  window never loads its dialog code.
94
+ Without a host drawer, the contextual sidebar uses its shared mobile sheet at
95
+ 48rem and below. With a host drawer, `narrowQuery` controls when the shell
96
+ replaces the desktop sidebar with it.
97
+
98
+ The sidebar's Ctrl/Meta+B shortcut yields to text inputs, textareas and editable
99
+ content visible in the event path. An editor inside a closed shadow root can stop
100
+ propagation of that chord to keep it from reaching the shell; the shell cannot
101
+ inspect the closed root's focused element.
88
102
 
89
103
  Consumers must import `@adea-ai/ui/globals.css` and configure Tailwind to scan
90
104
  the UI and framework package source. `tests/consumer` shows a buildable packed
@@ -174,10 +188,47 @@ surfaces stay in the window's account menu). Pass the result to Electrobun's
174
188
  `ApplicationMenu.setApplicationMenu` and route `application-menu-clicked` events
175
189
  through `createApplicationMenuHandler`. Help links must be HTTPS and open in the
176
190
  system browser; app-owned sections deliver their actions to the app.
191
+
192
+ For hosts that need macOS native roles without framework actions, pass
193
+ `macOS: { about: 'native', help: false }` and leave `settings` and `updates`
194
+ unset. The resulting application, Edit, View and Window menus retain system key
195
+ equivalents. A host can separately enable Settings and choose
196
+ `settingsAccelerator: false` or an app-owned `settingsAction` under `macOS`;
197
+ these settings options apply only when `settings: true`. Route an app-owned
198
+ action through the handler's `action` callback. To disable the native menu
199
+ entirely, the host should skip installation. Help links cannot be
200
+ supplied when the macOS Help menu is disabled. These presentation options do
201
+ not change Windows menus. Native menu callbacks may require the app adapter to
202
+ defer UI work until after the callback returns.
177
203
  `createApplicationCommandBroadcaster` registers the `shell.commands` desktop
178
204
  stream, and `connectApplicationCommands` in the window opens About, Settings,
179
205
  Help and Updates through `ApplicationUtilities` commands. Commands carry only a
180
206
  name over the authenticated channel. The generated app wires both sides.
207
+ The command connection does not renew credentials or retry after a disconnect.
208
+ When the app's authorization policy permits a new channel, its owner can explicitly
209
+ reconnect and then attach the menu stream:
210
+
211
+ ```ts
212
+ const disconnect = await connectApplicationCommands(client, commands)
213
+ // Later, after the app decides its current authorization permits reconnecting:
214
+ try {
215
+ const session = await client.reconnectForStreams()
216
+ await disconnect.resubscribe(session)
217
+ } catch {
218
+ // The app handles a failed reconnect or attachment according to its own policy.
219
+ }
220
+ // On teardown:
221
+ disconnect()
222
+ ```
223
+
224
+ The token works only with its originating client and current unexpired channel;
225
+ resubscription never obtains a bootstrap. Concurrent resubscription attempts are
226
+ rejected, and disposal closes a late result. The owner handles errors and chooses
227
+ whether to retry. Messages delivered before an initial or replacement stream is admitted are dropped,
228
+ not queued or replayed. An initial stream setup still uses normal
229
+ channel acquisition. Server revocation is not locally observable until a request
230
+ or transport event reveals it. The generated app and ordinary `reconnect()` do not
231
+ use this opt-in API and do not automatically recover from expiry or a transient close.
181
232
 
182
233
  `defineApplication` validates an app's identity, storage key, unique view IDs,
183
234
  initial view, labels and render functions. `Application` mounts those views in
@@ -209,6 +260,18 @@ for donor attribution.
209
260
  format, including the separate recovery key and the original color-contrast
210
261
  validation. The appearance host combines the published built-in catalogue with
211
262
  the imported variants. The appearance editor handles theme import and editing.
263
+ Its persisted import and removal operations hold a read/write transaction in a
264
+ shared origin-wide IndexedDB database while they update the readable version-1
265
+ library record. They also use Web Locks when available. The IndexedDB transaction
266
+ coordinates separate WebViews even when their Web Lock managers are not shared;
267
+ durable operations fail closed when IndexedDB is unavailable. These locks cannot
268
+ coordinate older builds or consumers that write the storage key through the
269
+ legacy synchronous `setCustomThemes`, `removeCustomTheme`, or
270
+ `importCustomTheme` API. The synchronous setter and remover are retained for
271
+ in-memory callers, but now fail closed when passed storage; the synchronous import
272
+ helper has been removed. Use the asynchronous mutation APIs for durable changes.
273
+ Older already-loaded builds can still write the version-1 key without the lock and
274
+ are not coordinated by this build.
212
275
 
213
276
  `appearance-host` supplies the V2 appearance provider and context, including
214
277
  imported variants, draft previews, native translucency capability, and a
@@ -218,6 +281,7 @@ available for apps using their own storage key. The appearance editor can be pro
218
281
 
219
282
  `appearance-surface` exports the shared appearance editor and its popover,
220
283
  including reversible previews, theme-file import, and font and surface settings.
284
+ Theme-file imports accept JSON files up to 1 MiB and reject larger files before reading them.
221
285
  Use it with the V2 appearance provider; pass `AppearancePanel` as the utilities
222
286
  appearance slot. Desktop hosts can register a native surface mirror through
223
287
  `window-surface`. The host remains responsible for implementing the native
@@ -245,8 +309,18 @@ metadata, but authenticates with the channel credentials rather than headers.
245
309
  The gateway bounds concurrent requests and body-read time. Invoke bodies are
246
310
  limited to 256 KiB unless a service registers a larger `maxBodyBytes` (at most
247
311
  16 MiB); that limit applies to that service alone. Native bootstrap
248
- delivery, streaming, window lifecycle, timeouts for service work, and
249
- application-specific authorization remain host work.
312
+ delivery, streaming, window lifecycle, and application-specific authorization
313
+ remain host work. Service-work deadlines are opt-in with `dispatchTimeoutMs`;
314
+ when omitted, service dispatch has no deadline. When configured, an expired
315
+ deadline returns HTTP 504 and aborts the `AbortSignal` passed to service
316
+ `authorize` and `run` callbacks. Set it on `createDesktopGateway` or
317
+ `startDesktopHost`. A caller abort also aborts that signal; since
318
+ the caller may already be disconnected, the host must not rely on delivering a
319
+ response for that cancellation. Abort is cooperative: JavaScript cannot stop a
320
+ synchronous or signal-ignoring callback, and a timeout or disconnect does not
321
+ prove its side effects stopped. The gateway keeps the concurrency slot until
322
+ the dispatch settles, and retries after an ambiguous timeout can duplicate
323
+ effects.
250
324
 
251
325
  `renderer-profile` selects the desktop renderer consistently for both the
252
326
  Electrobun build and window. `createRendererProfile()` selects the operating
@@ -268,10 +342,13 @@ service client. The host creates a blank window with Electrobun's bridge
268
342
  sandbox enabled, installs its
269
343
  navigation rules, and only then loads the loopback client. The client obtains a
270
344
  window-bound bootstrap, signs service calls and supports explicit reconnect;
271
- it does not replay a failed call. Set `portFile` to a path in an existing,
345
+ it does not replay a failed call. Disposing the client or explicitly reconnecting
346
+ aborts in-flight invoke requests; server work observes cooperative cancellation,
347
+ so side effects may already have occurred when the call rejects. Set `portFile` to a path in an existing,
272
348
  app-owned data directory to preserve the loopback origin and its browser
273
- preferences across restarts. A malformed record or occupied port fails closed;
274
- the host never silently selects a new origin. Electrobun 2.0.5 configures CEF
349
+ preferences across restarts. First publication requires hard-link support in that
350
+ directory; unsupported filesystems fail closed. A malformed record or occupied
351
+ port also fails closed; the host never silently selects a new origin. Electrobun 2.0.5 configures CEF
275
352
  with Chromium's operating-system sandbox disabled; the bridge sandbox and
276
353
  web-security flags do not provide that OS process isolation. A packaged native
277
354
  probe exercises both
@@ -311,7 +388,17 @@ workflows on the shared schedule (pinned to the release tag; run
311
388
  `bunx adea-update-app-framework` to pin the commit) and stay off until the
312
389
  repository sets `DESKTOP_RELEASES_ENABLED=true` with a release signing key.
313
390
  Native application services and product-specific authorization must still be
314
- added before distribution. Run `bun run test:generated` for an isolated packed-consumer web
391
+ added before distribution. Generation writes into a private staging directory
392
+ next to the destination and publishes it with one no-replace rename, so a failed
393
+ or concurrent run never leaves a partial destination and a retry can proceed. It
394
+ refuses a destination parent that another user owns, that other users can write
395
+ to, or that is group-writable by a group not provably private to the user (sticky
396
+ parents are accepted). On Linux a group counts as private when `/etc/passwd` and
397
+ `/etc/group` show no other account in it; elsewhere a group-writable parent is
398
+ refused. Cleanup removes the staging directory only while it is still the one the
399
+ run created. A run killed mid-generation can leave a `.framework-app-*`
400
+ directory beside the destination; it never blocks a retry and is safe to delete.
401
+ Run `bun run test:generated` for an isolated packed-consumer web
315
402
  build and browser check; `bun scripts/test-generated.ts --desktop` additionally
316
403
  builds the native bundle for the current platform.
317
404
 
@@ -358,10 +445,20 @@ as Electrobun's own build does (CMake and Xcode on macOS, CMake and g++ on
358
445
  Linux, CMake and Visual Studio C++ on Windows). The result is cached under
359
446
  `ADEA_CEF_HELPER_CACHE` when set, otherwise the user cache directory;
360
447
  `adea-cef-helper key` prints the cache key for CI and `adea-cef-helper build`
361
- fills the cache ahead of a build. The packaged native probe loads a cross-site
448
+ fills the cache ahead of a build. Each completed entry records its key, size and
449
+ SHA-256, which are checked before reuse and after a concurrent build. A missing
450
+ or corrupt record or helper stops the build: remove that key's directory from
451
+ the cache root and retry to rebuild it. The record detects accidental corruption;
452
+ it does not authenticate a cache that an attacker can modify. The packaged native probe loads a cross-site
362
453
  frame in an unsandboxed CEF window and requires all four bridges in the main
363
454
  frame and none in the subframe.
364
455
 
456
+ Helper hashing and replacement use fixed-size buffers. Keep the cache and build
457
+ tree private and stable while the hook runs: path checks cannot make multiple
458
+ file replacements atomic. If a replacement fails, the build stops before
459
+ signing; rebuild the output tree before retrying because earlier helpers may
460
+ already have been replaced.
461
+
365
462
  `release-publication` validates installer receipts and signed discovery
366
463
  descriptors against the exact staged payloads before publication. It refuses
367
464
  asset replacement, rechecks source and workflow provenance, uploads the
@@ -532,6 +629,11 @@ of a commit on the fetched `origin/main`: version state comes from the feed's
532
629
  ledger, read anonymously, and the commit itself stands in for the workflow run.
533
630
  Nothing is uploaded; publishing steps write a tree mirroring the feed's keys and
534
631
  `upload-plan.json`, ordered assets, release.json, index.json, channel pointers.
632
+ These plans are snapshots, not conditional writes or transactions. Serialize all
633
+ writers for an app's feed from the initial read through the last upload, including
634
+ promotion and platform additions. If the feed changes before a plan is applied,
635
+ discard that plan and stage a fresh one; uploading stale plans can replace a
636
+ newer release inventory or channel pointer.
535
637
 
536
638
  - `adea-cut-release --local dev|daily <config> <sha>` prints the tag and
537
639
  `dispatched` when this machine's platform still has to be built.
@@ -570,9 +672,22 @@ already pin an exact version. It rewrites those versions, pins every framework
570
672
  workflow to the source commit (`@<sha> # v<version>`), regenerates `bun.lock`
571
673
  with `bun install` (keeping comments such as release-please's version marker),
572
674
  checks the lock names exactly that version and integrity, and then requires
573
- `bun install --frozen-lockfile` to pass. If any step fails, it restores every
574
- file it touched. Keep the framework out of dependency bots so they cannot move
575
- one of the three on its own.
675
+ `bun install --frozen-lockfile` to pass without changing the verified lock.
676
+ Only direct entries in the four top-level dependency sections are rewritten;
677
+ unrelated properties retain their original bytes. Ambiguous duplicate dependency
678
+ keys and manifests nested more than 256 levels are rejected before any writes.
679
+ The command replaces regular files using same-directory temporary files and
680
+ preserves their permission bits. Replacement changes the file identity and
681
+ does not preserve ownership, ACLs, extended attributes, or hard links; it
682
+ refuses symlinked files. On failure, rollback preserves unexpected contents and
683
+ reports affected paths instead of overwriting them. A lock in the Git worktree prevents
684
+ two copies of this command from updating it simultaneously. Other editors and
685
+ installs do not honor that lock, and the checks and writes are not atomic with
686
+ respect to them, so stop those before running it. If a process
687
+ is interrupted and leaves the lock behind, verify no updater is still running
688
+ before removing the empty directory printed by `git rev-parse --git-path
689
+ adea-framework-update.lock`. Keep the framework out of dependency bots so they
690
+ cannot move one of the three on its own.
576
691
 
577
692
  ### Task cache toolchain identity
578
693
 
@@ -789,7 +904,12 @@ app without `commandArtifacts` publishes exactly as before.
789
904
  `update-manager` coordinates signed discovery, version policy, explicit approval
790
905
  of the exact version, and verified download. Its `staged` state reports only
791
906
  that an application-supplied platform adapter accepted the download;
792
- `desktop-updater` applies it.
907
+ `desktop-updater` applies it. Trust is checked before and after download, but
908
+ the stage adapter must independently enforce trust at its commit boundary.
909
+ Before the stage callback is invoked, rejected built-in downloads are discarded
910
+ from the configured private, app-owned download root. An injected downloader's
911
+ results are retained unless the caller supplies `discardDownload`. Once stage is
912
+ invoked, it owns the download, including cleanup on failure.
793
913
 
794
914
  `update-extraction` rechecks a signed archive, bounds Zstandard expansion, and
795
915
  extracts into a new private staging directory using strict tar handling. It
@@ -804,12 +924,17 @@ channel descriptors with the app's Ed25519 key. It refuses an untrusted key or
804
924
  existing output. Signing and staging do not publish or qualify a release.
805
925
 
806
926
  `adea-release-step qualify-upgrade` (an app's `release:qualify-upgrade`) runs after signing
807
- on each platform and before publication. It discovers the newest published release
808
- the way the app's updater does (the same channel, or dev before a channel's first
927
+ on each platform and before publication. It selects the highest earlier version in the
928
+ feed ledger (the same channel, or dev before a channel's first
809
929
  release), installs it with its own installer, then stages and swaps in this
810
930
  release's signed payload and observes the new version start under the same guard
811
931
  and offline policy as the installer receipt. With no earlier published release it
812
- reports that and passes.
932
+ reports that and passes. If the selected release does not advertise this platform's
933
+ descriptor, or its metadata or descriptor cannot be verified, qualification fails
934
+ rather than silently falling back to an older version or treating it as no prior
935
+ release. In a partial-platform feed this may require publishing that platform before
936
+ qualification can proceed. The ledger is unsigned, so selection is limited to the
937
+ versions it advertises and cannot prove that the feed omitted no release.
813
938
 
814
939
  An optional release `offlinePolicy` binds qualification to an app-owned visible
815
940
  marker. `standalone` is for apps with no startup bootstrap; `local-bootstrap`
@@ -950,7 +1075,12 @@ that a renderer's existing profile or stored data has been migrated.
950
1075
 
951
1076
  A desktop host exposes `revokeChannels()` for an app to invalidate current
952
1077
  window channels and close their streams when authorization changes. The
953
- window's native grant remains valid, so its client can explicitly reconnect.
1078
+ window's native grant remains valid until its fixed 12-hour deadline or window
1079
+ closure, so its client can explicitly reconnect only before that deadline. A
1080
+ channel acquired shortly before the deadline can outlive the grant, but once
1081
+ that channel expires or is revoked the window cannot reconnect. A new host and
1082
+ window are currently required; apps must preserve unsaved work before replacing
1083
+ them. No automatic grant renewal is implemented.
954
1084
  The app must update and enforce its own authorization scope before revocation;
955
1085
  this method does not replace or rebind the principal supplied at host creation
956
1086
  and cannot cancel a service handler that has already begun.
@@ -973,8 +1103,12 @@ Generated apps can declare custom URL schemes in `src/app-config.ts`. On macOS,
973
1103
  Electrobun places the schemes in the app bundle; platform-specific callback
974
1104
  delivery still needs qualification. `createOpenUrlChannel` can subscribe to the
975
1105
  native `open-url` event before asynchronous startup and buffer a bounded number
976
- of events until the app attaches a receiver. URLs are untrusted input: the app
977
- must validate the callback target, parameters, state and replay protection.
1106
+ of events until the app attaches a receiver. It accepts both `Electrobun.events`
1107
+ event envelopes and the unwrapped payload from `Electrobun.app.on`. Disposal
1108
+ ignores later callbacks and unregisters the listener when the source provides a
1109
+ working unsubscribe or listener-removal method. For removable listeners, prefer
1110
+ `Electrobun.events`: Electrobun 2.0.5's native `app.on` returns a no-op
1111
+ unsubscriber and retains its wrapper. URLs are untrusted input: the app must validate the callback target, parameters, state and replay protection.
978
1112
  Async receivers start in delivery order but can finish concurrently.
979
1113
 
980
1114
  ### Sidecar host
@@ -1004,6 +1138,10 @@ calls it through `desktop-client`; a sidecar failure arrives as
1004
1138
  Ship each sidecar at `Resources/app/sidecars/<name>` (`<name>.exe` on Windows):
1005
1139
  stage the binary built for the target OS, for example in `build/sidecars`, and
1006
1140
  copy it with Electrobun's `build.copy` (`{ 'build/sidecars': 'sidecars' }`).
1141
+ Windows targets reject reserved device names such as `con`, `nul`, `com1`, and
1142
+ `lpt1`, even with the `.exe` extension. Names used only on Linux or macOS retain
1143
+ their existing validation. Release configurations require Windows support and
1144
+ therefore reject those names before packaging.
1007
1145
  Resolve it at runtime with `packagedSidecarPath(import.meta.dir, name)` from
1008
1146
  `app-bundle`. List the names in the release configuration as
1009
1147
  `"sidecars": ["name"]`: installer qualification then requires each sidecar in
@@ -16,16 +16,23 @@ export type ApplicationDefinition = Readonly<{
16
16
  initialView: string;
17
17
  views: readonly ApplicationView[];
18
18
  }>;
19
+ /**
20
+ * A host router may expose a Solid-reactive `current` getter. Plain mutable
21
+ * routers must implement `subscribe` to report route changes made outside the
22
+ * Application; navigation requested by the Application always causes a refresh.
23
+ */
24
+ export type ApplicationRouter = Readonly<{
25
+ current(): string;
26
+ navigate(id: string): void;
27
+ subscribe?(listener: () => void): () => void;
28
+ }>;
19
29
  /** Validate the static app identity and destinations before the UI mounts. */
20
30
  export declare function defineApplication(definition: ApplicationDefinition): ApplicationDefinition;
21
31
  export type ApplicationProps = {
22
32
  definition: ApplicationDefinition;
23
33
  runtime: 'desktop' | 'web';
24
34
  /** Supply a router when navigation is externally owned; otherwise the app keeps local state. */
25
- router?: {
26
- current(): string;
27
- navigate(id: string): void;
28
- };
35
+ router?: ApplicationRouter;
29
36
  utilities?: Omit<ApplicationUtilitiesProps, 'identity' | 'runtime'>;
30
37
  theme?: Omit<ThemeProviderProps, 'children' | 'storageKey'>;
31
38
  /** Replace the default provider to retain an existing appearance contract. */
@@ -1,7 +1,7 @@
1
1
  import { ApplicationShell } from "../shell/app-shell.js";
2
2
  import { ApplicationThemeProvider, ApplicationUtilities } from "../shell/app-utilities.js";
3
3
  import { createComponent, memo, mergeProps } from "solid-js/web";
4
- import { createMemo, createSignal } from "solid-js";
4
+ import { createEffect, createMemo, createSignal, onCleanup } from "solid-js";
5
5
  // src/app/application.tsx
6
6
  /** Validate the static app identity and destinations before the UI mounts. */
7
7
  function defineApplication(definition) {
@@ -22,11 +22,31 @@ function defineApplication(definition) {
22
22
  /** Mount shared UI chrome from an app's own views and identity. */
23
23
  function Application(props) {
24
24
  const [localView, setLocalView] = createSignal(props.definition.initialView);
25
- const view = createMemo(() => props.definition.views.find((item) => item.id === (props.router?.current() ?? localView())) ?? props.definition.views.find((item) => item.id === props.definition.initialView));
25
+ const [routerRevision, setRouterRevision] = createSignal(0);
26
+ createEffect(() => {
27
+ const router = props.router;
28
+ if (!router?.subscribe) return;
29
+ let active = true;
30
+ const unsubscribe = router.subscribe(() => {
31
+ if (active) setRouterRevision((revision) => revision + 1);
32
+ });
33
+ onCleanup(() => {
34
+ active = false;
35
+ unsubscribe();
36
+ });
37
+ });
38
+ const view = createMemo(() => {
39
+ routerRevision();
40
+ return props.definition.views.find((item) => item.id === (props.router?.current() ?? localView())) ?? props.definition.views.find((item) => item.id === props.definition.initialView);
41
+ });
26
42
  const navigate = (id) => {
27
43
  if (!props.definition.views.some((item) => item.id === id)) return;
28
- if (props.router) props.router.navigate(id);
29
- else setLocalView(id);
44
+ if (!props.router) return setLocalView(id);
45
+ try {
46
+ props.router.navigate(id);
47
+ } finally {
48
+ setRouterRevision((revision) => revision + 1);
49
+ }
30
50
  };
31
51
  const Theme = props.themeProvider ?? ((providerProps) => createComponent(ApplicationThemeProvider, mergeProps(() => props.theme, {
32
52
  get storageKey() {
@@ -1,4 +1,5 @@
1
1
  import { type DesktopRenderer } from '../native/renderer-profile';
2
+ import { type AccountDatabase } from './private-group';
2
3
  /** Generate a new app without replacing an existing directory. */
3
4
  export declare function createApplication(options: {
4
5
  directory: string;
@@ -8,6 +9,14 @@ export declare function createApplication(options: {
8
9
  sourceUrl: string;
9
10
  frameworkSpecifier: string;
10
11
  renderer?: DesktopRenderer;
12
+ }, dependencies?: {
13
+ templateDirectory?: string;
14
+ /** Synchronize publish races in tests; app creation does not need this hook. */
15
+ beforePublish?: (staging: string) => void | Promise<void>;
16
+ /** Replace staging removal in tests to exercise cleanup failure. */
17
+ removeDirectory?: (path: string) => Promise<void>;
18
+ /** Replace the local account database in tests of group-writable parents. */
19
+ readAccounts?: () => Promise<AccountDatabase | undefined>;
11
20
  }): Promise<{
12
21
  directory: string;
13
22
  }>;