@adea-ai/app-framework 0.39.3 → 0.39.4

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 (199) hide show
  1. package/README.md +158 -52
  2. package/dist/app/application.d.ts +0 -1
  3. package/dist/app/application.js +8 -6
  4. package/dist/app/create-application.js +3 -11
  5. package/dist/app/service-registry.d.ts +0 -1
  6. package/dist/app/service-registry.js +3 -3
  7. package/dist/app/value-guards.d.ts +2 -0
  8. package/dist/app/value-guards.js +6 -1
  9. package/dist/appearance/appearance-host.d.ts +1 -1
  10. package/dist/appearance/appearance-host.js +11 -2
  11. package/dist/appearance/appearance-preferences.d.ts +0 -1
  12. package/dist/appearance/custom-theme-import.d.ts +8 -2
  13. package/dist/appearance/custom-theme-import.js +58 -23
  14. package/dist/appearance/custom-theme-library.d.ts +3 -3
  15. package/dist/appearance/custom-theme-library.js +3 -3
  16. package/dist/appearance/theme-file-importer.d.ts +1 -1
  17. package/dist/appearance/theme-file-importer.js +2 -1
  18. package/dist/appearance/theme-library-mutation.d.ts +7 -0
  19. package/dist/appearance/theme-library-mutation.js +10 -2
  20. package/dist/appearance/theme-library-store.d.ts +17 -13
  21. package/dist/appearance/theme-library-store.js +35 -22
  22. package/dist/appearance/theme-record-adapter.js +1 -2
  23. package/dist/appearance/theme-registry.js +0 -1
  24. package/dist/cli/cli-runner.d.ts +3 -2
  25. package/dist/cli/cli-runner.js +5 -10
  26. package/dist/cli/release-assets-plan-cli.js +2 -2
  27. package/dist/cli/release-cut-cli.js +2 -3
  28. package/dist/cli/release-descriptor-staging-cli.js +2 -2
  29. package/dist/cli/release-finalize-cli.js +3 -3
  30. package/dist/cli/release-promote-cli.js +2 -2
  31. package/dist/cli/release-publish-cli.js +2 -2
  32. package/dist/cli/release-sign-cli.js +2 -1
  33. package/dist/cli/release-step-cli.js +2 -2
  34. package/dist/desktop/channel-proof.js +27 -11
  35. package/dist/desktop/client-assets.d.ts +6 -1
  36. package/dist/desktop/client-assets.js +16 -3
  37. package/dist/desktop/client-dev-proxy.d.ts +0 -2
  38. package/dist/desktop/client-dev-proxy.js +2 -2
  39. package/dist/desktop/desktop-client.js +2 -1
  40. package/dist/desktop/desktop-gateway.js +24 -82
  41. package/dist/desktop/desktop-host-websocket.d.ts +5 -1
  42. package/dist/desktop/desktop-host-websocket.js +9 -7
  43. package/dist/desktop/desktop-host.d.ts +5 -0
  44. package/dist/desktop/desktop-host.js +3 -0
  45. package/dist/desktop/desktop-stream.js +5 -10
  46. package/dist/desktop/typed-array-intrinsics.d.ts +6 -0
  47. package/dist/desktop/typed-array-intrinsics.js +13 -1
  48. package/dist/developer-app/developer-app.d.ts +1 -1
  49. package/dist/developer-app/developer-app.js +26 -13
  50. package/dist/framework-source.json +1 -1
  51. package/dist/installer/command-artifact.d.ts +1 -0
  52. package/dist/installer/command-artifact.js +47 -27
  53. package/dist/installer/installed-payload.js +3 -1
  54. package/dist/installer/installer-ci-bootstrap.js +5 -6
  55. package/dist/installer/installer-ci-preflight.js +3 -3
  56. package/dist/installer/installer-identity.d.ts +0 -22
  57. package/dist/installer/installer-identity.js +3 -53
  58. package/dist/installer/installer-image-mount.d.ts +0 -1
  59. package/dist/installer/installer-image-mount.js +1 -1
  60. package/dist/installer/installer-observation.d.ts +5 -5
  61. package/dist/installer/installer-observation.js +32 -47
  62. package/dist/installer/installer-process-cleanup.js +2 -2
  63. package/dist/installer/installer-renderer-evidence.js +7 -28
  64. package/dist/installer/installer-upgrade-command.js +8 -20
  65. package/dist/installer/installer-worker-guard.js +3 -3
  66. package/dist/native/cef-helper.js +4 -4
  67. package/dist/native/desktop-build.d.ts +0 -3
  68. package/dist/native/desktop-build.js +2 -2
  69. package/dist/native/electrobun-source-patch.d.ts +4 -0
  70. package/dist/native/electrobun-source-patch.js +5 -1
  71. package/dist/native/native-utilities.js +4 -3
  72. package/dist/native/pinned-download.d.ts +16 -0
  73. package/dist/native/pinned-download.js +42 -0
  74. package/dist/native/posix-launcher-build.js +15 -35
  75. package/dist/native/posix-tree-removal.js +21 -33
  76. package/dist/native/sidecar-services.d.ts +0 -2
  77. package/dist/native/sidecar-services.js +1 -1
  78. package/dist/native/sidecar.d.ts +3 -0
  79. package/dist/native/sidecar.js +15 -2
  80. package/dist/native/window-surface-store.js +3 -3
  81. package/dist/native/windows-extractor-build.d.ts +6 -16
  82. package/dist/native/windows-extractor-build.js +11 -14
  83. package/dist/release/feed-release-cut.d.ts +2 -6
  84. package/dist/release/feed-release-cut.js +5 -93
  85. package/dist/release/feed-state.js +1 -5
  86. package/dist/release/github-release-cut.js +5 -66
  87. package/dist/release/github-release-provenance.d.ts +2 -0
  88. package/dist/release/github-release-provenance.js +4 -7
  89. package/dist/release/github-release-publisher.js +2 -2
  90. package/dist/release/github-release-qualification.js +3 -3
  91. package/dist/release/local-release.d.ts +3 -3
  92. package/dist/release/local-release.js +12 -23
  93. package/dist/release/qualification-run.js +1 -1
  94. package/dist/release/release-assets-plan.js +1 -1
  95. package/dist/release/release-config.d.ts +7 -15
  96. package/dist/release/release-config.js +25 -29
  97. package/dist/release/release-cut-command.d.ts +1 -1
  98. package/dist/release/release-cut-command.js +1 -1
  99. package/dist/release/release-cut.d.ts +5 -32
  100. package/dist/release/release-cut.js +9 -55
  101. package/dist/release/release-descriptor-staging.js +3 -8
  102. package/dist/release/release-promotion.js +2 -1
  103. package/dist/release/release-publish-command.js +5 -15
  104. package/dist/release/release-qualification.js +1 -1
  105. package/dist/shared/bounded-body.d.ts +33 -0
  106. package/dist/shared/bounded-body.js +102 -0
  107. package/dist/shared/file-system.d.ts +12 -0
  108. package/dist/shared/file-system.js +40 -0
  109. package/dist/shell/app-shell.js +29 -14
  110. package/dist/shell/app-utilities.d.ts +2 -1
  111. package/dist/shell/app-utilities.js +2 -1
  112. package/dist/shell/application-menu.d.ts +1 -1
  113. package/dist/shell/application-menu.js +7 -3
  114. package/dist/shell/poll.d.ts +27 -0
  115. package/dist/shell/poll.js +88 -0
  116. package/dist/update-helper.bundle.js +268 -144
  117. package/dist/updates/channel-update-manager.js +0 -1
  118. package/dist/updates/desktop-updater.d.ts +9 -0
  119. package/dist/updates/desktop-updater.js +103 -50
  120. package/dist/updates/feed/release-feed.d.ts +7 -4
  121. package/dist/updates/feed/release-feed.js +3 -7
  122. package/dist/updates/feed/release-location.js +6 -26
  123. package/dist/updates/feed/release-version.d.ts +7 -2
  124. package/dist/updates/feed/release-version.js +9 -2
  125. package/dist/updates/feed/signed-release.d.ts +1 -1
  126. package/dist/updates/feed/signed-release.js +2 -2
  127. package/dist/updates/feed/update-discovery.js +2 -6
  128. package/dist/updates/helper/launch-gate-recovery.js +28 -78
  129. package/dist/updates/helper/resume-staging.d.ts +14 -3
  130. package/dist/updates/helper/resume-staging.js +23 -37
  131. package/dist/updates/helper/update-helper.d.ts +6 -2
  132. package/dist/updates/helper/update-helper.js +38 -33
  133. package/dist/updates/helper/update-resume.js +9 -6
  134. package/dist/updates/install/update-extraction.js +28 -8
  135. package/dist/updates/install/update-handoff-plan.d.ts +0 -1
  136. package/dist/updates/install/update-handoff-plan.js +3 -4
  137. package/dist/updates/install/update-swap-stage.js +1 -6
  138. package/dist/updates/install/update-swap.d.ts +5 -2
  139. package/dist/updates/install/update-swap.js +193 -72
  140. package/dist/updates/launch/helper-exit-wait.d.ts +6 -0
  141. package/dist/updates/launch/helper-exit-wait.js +18 -0
  142. package/dist/updates/launch/packaged-update-startup.js +8 -6
  143. package/dist/updates/launch/update-launch-gate.js +7 -14
  144. package/dist/updates/locks/stable-file.js +4 -1
  145. package/dist/updates/locks/update-helper-presence.d.ts +12 -0
  146. package/dist/updates/locks/update-helper-presence.js +27 -0
  147. package/dist/updates/retention/retention-cleanup.js +10 -9
  148. package/dist/updates/retention/retention-maintenance.d.ts +40 -0
  149. package/dist/updates/retention/retention-maintenance.js +95 -0
  150. package/dist/updates/retention/retention-prune-progress.js +4 -5
  151. package/dist/updates/retention/retirement-inventory.d.ts +13 -0
  152. package/dist/updates/retention/retirement-inventory.js +39 -31
  153. package/dist/updates/retention/retirement-records.d.ts +1 -4
  154. package/dist/updates/retention/retirement-records.js +18 -32
  155. package/dist/updates/retention/update-retention-marker.d.ts +4 -0
  156. package/dist/updates/retention/update-retention-marker.js +9 -14
  157. package/dist/updates/retention/update-retirement.d.ts +12 -0
  158. package/dist/updates/retention/update-retirement.js +59 -31
  159. package/dist/updates/update-adapter.d.ts +1 -23
  160. package/dist/updates/update-adapter.js +31 -24
  161. package/dist/updates/update-channel-store.d.ts +2 -1
  162. package/dist/updates/update-channel-store.js +6 -4
  163. package/dist/updates/update-manager.js +2 -2
  164. package/dist/updates/update-services.d.ts +1 -1
  165. package/dist/updates/update-services.js +9 -4
  166. package/dist/updates/update-state-store.d.ts +0 -2
  167. package/dist/updates/update-state-store.js +5 -12
  168. package/dist/updates/update-state.d.ts +6 -10
  169. package/dist/updates/update-state.js +1 -1
  170. package/dist/views/app-help.d.ts +1 -1
  171. package/dist/views/app-help.js +1 -3
  172. package/dist/views/appearance-surface.js +15 -8
  173. package/dist/views/update-surface.d.ts +1 -3
  174. package/dist/views/update-surface.js +2 -2
  175. package/package.json +18 -16
  176. package/src/app/application.tsx +13 -6
  177. package/src/appearance/appearance-host.tsx +17 -7
  178. package/src/appearance/appearance-preferences.ts +0 -1
  179. package/src/appearance/custom-theme-import.ts +99 -26
  180. package/src/appearance/custom-theme-library.ts +3 -2
  181. package/src/appearance/theme-file-importer.ts +3 -2
  182. package/src/appearance/theme-library-mutation.ts +20 -8
  183. package/src/appearance/theme-library-schema.ts +7 -0
  184. package/src/appearance/theme-library-store.ts +41 -26
  185. package/src/desktop/client-assets.ts +27 -12
  186. package/src/shell/app-shell.tsx +33 -13
  187. package/src/shell/app-utilities.tsx +7 -1
  188. package/src/shell/poll.ts +125 -0
  189. package/src/updates/feed/release-version.ts +11 -3
  190. package/src/updates/update-adapter.ts +27 -44
  191. package/src/updates/update-state.ts +7 -13
  192. package/src/views/app-help.tsx +1 -1
  193. package/src/views/appearance-surface.tsx +36 -8
  194. package/src/views/update-surface.tsx +0 -4
  195. package/templates/application/.github/workflows/release-assets.yml +2 -2
  196. package/templates/application/README.md +3 -3
  197. package/dist/native/cef-helper-download.d.ts +0 -1
  198. package/dist/native/cef-helper-download.js +0 -35
  199. package/src/desktop/client-response-lifecycle.ts +0 -305
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@adea-ai/app-framework",
3
- "version": "0.39.3",
3
+ "version": "0.39.4",
4
4
  "license": "Apache-2.0",
5
5
  "repository": {
6
6
  "type": "git",
@@ -34,7 +34,6 @@
34
34
  "src/appearance",
35
35
  "src/desktop/client-assets.ts",
36
36
  "src/desktop/client-asset-stream.ts",
37
- "src/desktop/client-response-lifecycle.ts",
38
37
  "src/desktop/client-asset-manifest.ts",
39
38
  "src/native/*.patch",
40
39
  "src/native/electrobun-types.d.ts",
@@ -52,6 +51,7 @@
52
51
  "templates"
53
52
  ],
54
53
  "type": "module",
54
+ "sideEffects": false,
55
55
  "exports": {
56
56
  "./client-assets": "./src/desktop/client-assets.ts",
57
57
  "./client-asset-manifest": {
@@ -80,6 +80,16 @@
80
80
  "solid": "./src/shell/app-utilities.tsx",
81
81
  "import": "./dist/shell/app-utilities.js"
82
82
  },
83
+ "./media-query": {
84
+ "types": "./dist/shell/media-query.d.ts",
85
+ "solid": "./src/shell/media-query.ts",
86
+ "import": "./dist/shell/media-query.js"
87
+ },
88
+ "./poll": {
89
+ "types": "./dist/shell/poll.d.ts",
90
+ "solid": "./src/shell/poll.ts",
91
+ "import": "./dist/shell/poll.js"
92
+ },
83
93
  "./app-settings": {
84
94
  "types": "./dist/views/app-settings.d.ts",
85
95
  "solid": "./src/views/app-settings.tsx",
@@ -114,6 +124,10 @@
114
124
  "types": "./dist/desktop/loopback-policy.d.ts",
115
125
  "import": "./dist/desktop/loopback-policy.js"
116
126
  },
127
+ "./bounded-body": {
128
+ "types": "./dist/shared/bounded-body.d.ts",
129
+ "import": "./dist/shared/bounded-body.js"
130
+ },
117
131
  "./appearance-preferences": {
118
132
  "types": "./dist/appearance/appearance-preferences.d.ts",
119
133
  "solid": "./src/appearance/appearance-preferences.ts",
@@ -199,10 +213,6 @@
199
213
  "types": "./dist/release/github-release-publisher.d.ts",
200
214
  "import": "./dist/release/github-release-publisher.js"
201
215
  },
202
- "./windows-runtime-patch": {
203
- "types": "./dist/native/windows-runtime-patch.d.ts",
204
- "import": "./dist/native/windows-runtime-patch.js"
205
- },
206
216
  "./release-promotion": {
207
217
  "types": "./dist/release/release-promotion.d.ts",
208
218
  "import": "./dist/release/release-promotion.js"
@@ -275,14 +285,6 @@
275
285
  "types": "./dist/updates/feed/release-feed.d.ts",
276
286
  "import": "./dist/updates/feed/release-feed.js"
277
287
  },
278
- "./release-location": {
279
- "types": "./dist/updates/feed/release-location.d.ts",
280
- "import": "./dist/updates/feed/release-location.js"
281
- },
282
- "./update-process-liveness": {
283
- "types": "./dist/updates/locks/update-process-liveness.d.ts",
284
- "import": "./dist/updates/locks/update-process-liveness.js"
285
- },
286
288
  "./update-manager": {
287
289
  "types": "./dist/updates/update-manager.d.ts",
288
290
  "import": "./dist/updates/update-manager.js"
@@ -406,8 +408,8 @@
406
408
  "registry": "https://registry.npmjs.org/"
407
409
  },
408
410
  "scripts": {
409
- "test": "bun test --timeout=$(bun -e \"process.stdout.write(process.env.ADEA_TEST_TIMEOUT_MS || '5000')\") tests/*/*.test.ts tests/*/*/*.test.ts && bun run test:ui",
410
- "test:ui": "bun test --isolate --timeout=$(bun -e \"process.stdout.write(process.env.ADEA_TEST_TIMEOUT_MS || '5000')\") --conditions=browser --preload @adea-ai/ui/testing/solid-transform tests/*/*.test.tsx",
411
+ "test": "bun test --parallel=$(bun -e \"process.stdout.write(process.env.ADEA_TEST_WORKERS || '4')\") --timeout=$(bun -e \"process.stdout.write(process.env.ADEA_TEST_TIMEOUT_MS || '5000')\") --timings=tests/test-timings.json tests/*/*.test.ts tests/*/*/*.test.ts && bun run test:ui",
412
+ "test:ui": "bun test --parallel=$(bun -e \"process.stdout.write(process.env.ADEA_TEST_WORKERS || '4')\") --timeout=$(bun -e \"process.stdout.write(process.env.ADEA_TEST_TIMEOUT_MS || '5000')\") --conditions=browser --preload @adea-ai/ui/testing/solid-transform tests/*/*.test.tsx",
411
413
  "test:sidebar-responsive-matrix": "bash scripts/test-sidebar-responsive-matrix.sh",
412
414
  "test:theme-browser": "bun scripts/test-theme-library-browser.ts",
413
415
  "build": "vp build && tsc -p tsconfig.json --emitDeclarationOnly && bun build src/cli/update-helper-cli.ts --target=bun --outfile dist/update-helper.bundle.js && bun scripts/write-framework-source.ts",
@@ -84,7 +84,6 @@ export type ApplicationProps = {
84
84
  onSearch?: () => void
85
85
  searchLabel?: string
86
86
  searchKeys?: readonly string[]
87
- navigationControls?: JSX.Element
88
87
  workspace?: JSX.Element
89
88
  search?: JSX.Element
90
89
  actions?: JSX.Element
@@ -138,8 +137,12 @@ export function Application(props: ApplicationProps) {
138
137
  {providerProps.children}
139
138
  </ApplicationThemeProvider>
140
139
  ))
141
- return (
142
- <Theme>
140
+ // The shell reads these props many times, and a getter would rebuild them on every read.
141
+ // The memos live under the theme provider so view code sees its context.
142
+ const Shell = () => {
143
+ const content = createMemo(() => view().render())
144
+ const sidebar = createMemo(() => view().sidebar?.())
145
+ return (
143
146
  <ApplicationShell
144
147
  name={props.definition.identity.name}
145
148
  mark={props.definition.mark}
@@ -147,12 +150,11 @@ export function Application(props: ApplicationProps) {
147
150
  activeDestination={view().id}
148
151
  onNavigate={navigate}
149
152
  title={view().label}
150
- content={view().render()}
151
- sidebar={view().sidebar?.()}
153
+ content={content()}
154
+ sidebar={sidebar()}
152
155
  onSearch={props.onSearch}
153
156
  searchLabel={props.searchLabel}
154
157
  searchKeys={props.searchKeys}
155
- navigation={props.navigationControls}
156
158
  workspace={props.workspace}
157
159
  search={props.search}
158
160
  actions={props.actions}
@@ -177,6 +179,11 @@ export function Application(props: ApplicationProps) {
177
179
  )
178
180
  }
179
181
  />
182
+ )
183
+ }
184
+ return (
185
+ <Theme>
186
+ <Shell />
180
187
  </Theme>
181
188
  )
182
189
  }
@@ -43,12 +43,6 @@ import {
43
43
  } from './custom-theme-library'
44
44
  import { LEGACY_IMPORTED_THEME_TOKEN_PROJECTION } from './legacy-imported-theme-token-projection'
45
45
 
46
- export type {
47
- AppearanceMode,
48
- AppearancePreferencesV2,
49
- ResolvedAppearance,
50
- } from './appearance-preferences'
51
-
52
46
  /**
53
47
  * The shared theme context plus the V2 document seam the appearance editor works
54
48
  * in. Everything the shell reads (the selection, the resolved appearance, the
@@ -103,7 +97,7 @@ export function appearanceProviderProps(
103
97
  editorRoles: 'floor',
104
98
  tokenProjection: {
105
99
  rules: LEGACY_IMPORTED_THEME_TOKEN_PROJECTION,
106
- project: tokenProjector,
100
+ project: projectCachedTokens,
107
101
  },
108
102
  transformTokens: tokensAsHex,
109
103
  disableTransitionOnChange: true,
@@ -111,6 +105,22 @@ export function appearanceProviderProps(
111
105
  }
112
106
  }
113
107
 
108
+ // Imported theme tokens are frozen and identity-stable, so a theme the projection must repair
109
+ // pays the contrast search once instead of on every accent, mode or preview paint.
110
+ const projectedTokens = new WeakMap<object, Readonly<Record<string, string>>>()
111
+ function projectCachedTokens(
112
+ tokens: Parameters<typeof tokenProjector>[0],
113
+ rules: Parameters<typeof tokenProjector>[1]
114
+ ): ReturnType<typeof tokenProjector> {
115
+ if (rules !== LEGACY_IMPORTED_THEME_TOKEN_PROJECTION) return tokenProjector(tokens, rules)
116
+ let projected = projectedTokens.get(tokens)
117
+ if (!projected) {
118
+ projected = Object.freeze(tokenProjector(tokens, rules))
119
+ projectedTokens.set(tokens, projected)
120
+ }
121
+ return projected
122
+ }
123
+
114
124
  /**
115
125
  * The V2 view of a shared theme context. Reads derive from the provider's selection;
116
126
  * writes go through its `setSelection`, so the shared provider remains the only
@@ -58,7 +58,6 @@ export type AppearancePreferencesV2 = Readonly<{
58
58
  }>
59
59
 
60
60
  export type AppearanceMode = 'system' | 'light' | 'dark'
61
- export type ResolvedAppearance = 'light' | 'dark'
62
61
  export type SurfacePreference = 'opaque' | 'frosted' | 'translucent'
63
62
 
64
63
  export const APPEARANCE_STORAGE_KEY = 'appearance'
@@ -35,6 +35,7 @@ import {
35
35
  type AppearanceStorage,
36
36
  type CustomThemeStored,
37
37
  type ThemeLibraryMutationOptions,
38
+ type ThemeLibraryRecoveryReason,
38
39
  type StoredThemeColors as ThemeColors,
39
40
  type StoredThemeVariant as ThemeVariant,
40
41
  } from './custom-theme-library'
@@ -100,9 +101,26 @@ const SYNTAX_SOURCES = {
100
101
  } as const
101
102
 
102
103
  export type CustomThemeImportResult =
103
- | { ok: true; theme: CustomThemeStored }
104
+ | {
105
+ ok: true
106
+ theme: CustomThemeStored
107
+ /** The import replaced an unreadable library; see `CUSTOM_THEME_LIBRARY_RECOVERED`. */
108
+ recovered?: ThemeLibraryRecoveryReason
109
+ }
104
110
  | { ok: false; error: string }
105
111
 
112
+ /** A prepared theme still waiting for an id chosen against the latest library. */
113
+ type PreparedTheme = Readonly<{
114
+ name: string
115
+ appearance: 'light' | 'dark'
116
+ variant: ThemeVariant
117
+ flatTokens: Record<string, string>
118
+ /** Notes before and after the validation messages, which name the final id. */
119
+ notesBefore: readonly string[]
120
+ issueMessages: readonly string[]
121
+ notesAfter: readonly string[]
122
+ }>
123
+
106
124
  let fallbackThemeIdSequence = 0
107
125
 
108
126
  function slug(value: string): string {
@@ -182,6 +200,14 @@ function repairComponentContrast(variant: ThemeVariant, notes: string[]): ThemeV
182
200
  ...variant,
183
201
  colors: {
184
202
  ...colors,
203
+ // The canonical projection picks its own on-primary colour, which can miss the
204
+ // floor. Left unrepaired, every paint also re-runs a failing sidebar search.
205
+ primaryForeground: repairToFloor(
206
+ colors.primaryForeground,
207
+ colors.primary,
208
+ notes,
209
+ 'primary foreground'
210
+ ),
185
211
  cardForeground: repairToFloor(colors.cardForeground, colors.card, notes, 'card foreground'),
186
212
  popoverForeground: repairToFloor(
187
213
  colors.popoverForeground,
@@ -313,14 +339,14 @@ function projectCanonical(theme: AdeaTheme): ThemeVariant {
313
339
  }
314
340
 
315
341
  /**
316
- * Parse and store an uploaded theme. The only hard failure is unparseable
342
+ * Parse and project an uploaded theme. The only hard failure is unparseable
317
343
  * JSON: everything else normalizes, fills from the same-appearance default,
318
- * and reports what it had to adjust.
344
+ * and reports what it had to adjust. It does not read the library, so it runs
345
+ * before the shared lock is taken.
319
346
  */
320
347
  function prepareCustomTheme(
321
- text: string,
322
- existing: readonly CustomThemeStored[]
323
- ): CustomThemeImportResult {
348
+ text: string
349
+ ): { ok: true; prepared: PreparedTheme } | { ok: false; error: string } {
324
350
  let source: unknown
325
351
  try {
326
352
  source = JSON.parse(text)
@@ -338,12 +364,19 @@ function prepareCustomTheme(
338
364
 
339
365
  const notes: string[] = []
340
366
  const rawColors = (record.colors ?? {}) as Record<string, unknown>
367
+ // A file that names no appearance is read from its background, so a dark palette
368
+ // lands in the Dark menu instead of replacing the light theme.
341
369
  const appearance: 'light' | 'dark' =
342
370
  record.appearance === 'light' || record.appearance === 'dark'
343
371
  ? record.appearance
344
- : rawColors.background === undefined
345
- ? 'dark'
346
- : 'light'
372
+ : isHex(rawColors.background)
373
+ ? contrastRatio(rawColors.background, '#ffffff') >
374
+ contrastRatio(rawColors.background, '#000000')
375
+ ? 'dark'
376
+ : 'light'
377
+ : rawColors.background === undefined
378
+ ? 'dark'
379
+ : 'light'
347
380
  const base = defaultThemeRecord(appearance)
348
381
  const name =
349
382
  typeof record.name === 'string' && record.name.trim().length > 0
@@ -416,11 +449,14 @@ function prepareCustomTheme(
416
449
  variant = projectHostFallback(name, appearance, canonical.colors, ansi, notes)
417
450
  notes.push('Syntax roles were approximated from the ANSI ramp.')
418
451
  }
419
- variant = repairComponentContrast(variant, notes)
420
- variant = { ...variant, id: uniqueThemeId(name, existing), name }
452
+ variant = { ...repairComponentContrast(variant, notes), name }
421
453
 
422
- const issues = validateThemeRegistry([variant]).filter((issue) => issue.severity === 'error')
423
- for (const issue of issues) notes.push(`${issue.variantId}: ${issue.message}`)
454
+ // The validation checks this one variant's colours; its id only names the note.
455
+ // The id is never empty here, so the uniqueness check cannot fire.
456
+ const issueMessages = validateThemeRegistry([variant])
457
+ .filter((issue) => issue.severity === 'error')
458
+ .map((issue) => issue.message)
459
+ const notesBefore = notes.splice(0)
424
460
 
425
461
  const flatTokens = flatVariantTokens(variant)
426
462
  const projectedTokens = projectThemeTokens(flatTokens, LEGACY_IMPORTED_THEME_TOKEN_PROJECTION)
@@ -440,25 +476,58 @@ function prepareCustomTheme(
440
476
  notes.push(`“${role}” was adjusted for readable contrast.`)
441
477
  }
442
478
 
443
- const stored: CustomThemeStored = {
444
- id: variant.id,
445
- name: variant.name,
446
- appearance,
479
+ return {
480
+ ok: true,
481
+ prepared: {
482
+ name,
483
+ appearance,
484
+ variant,
485
+ flatTokens,
486
+ notesBefore,
487
+ issueMessages,
488
+ notesAfter: notes,
489
+ },
490
+ }
491
+ }
492
+
493
+ /** Name the prepared theme against the latest library snapshot. */
494
+ function storedTheme(
495
+ prepared: PreparedTheme,
496
+ existing: readonly CustomThemeStored[]
497
+ ): CustomThemeStored {
498
+ const id = uniqueThemeId(prepared.name, existing)
499
+ return {
500
+ id,
501
+ name: prepared.name,
502
+ appearance: prepared.appearance,
447
503
  importedAt: new Date().toISOString(),
448
- variant,
449
- flatTokens,
450
- notes,
504
+ variant: { ...prepared.variant, id },
505
+ flatTokens: prepared.flatTokens,
506
+ notes: [
507
+ ...prepared.notesBefore,
508
+ ...prepared.issueMessages.map((message) => `${id}: ${message}`),
509
+ ...prepared.notesAfter,
510
+ ],
451
511
  }
452
- return { ok: true, theme: stored }
453
512
  }
454
513
 
455
- /** Parse and add a theme using the latest snapshot inside the shared mutation lock. */
514
+ /**
515
+ * Parse and add a theme. Parsing, projection and contrast repair (tens of
516
+ * milliseconds) run before the shared lock; only the id choice against the latest
517
+ * snapshot and the write run inside it.
518
+ */
456
519
  export async function importCustomThemeAtomically(
457
520
  text: string,
458
521
  storage: AppearanceStorage | undefined,
459
522
  options: ThemeLibraryMutationOptions & { canCommit?: () => boolean } = {}
460
523
  ): Promise<CustomThemeImportResult> {
461
524
  const { canCommit, ...mutationOptions } = options
525
+ let prepared: ReturnType<typeof prepareCustomTheme> | undefined
526
+ try {
527
+ prepared = prepareCustomTheme(text)
528
+ } catch {
529
+ // Report it from inside the mutation, as a failed update, like before.
530
+ }
462
531
  const mutation = await mutateCustomThemeLibrary<CustomThemeImportResult>(
463
532
  storage,
464
533
  (existing) => {
@@ -469,13 +538,17 @@ export async function importCustomThemeAtomically(
469
538
  value: { ok: false, error: 'This import was superseded.' },
470
539
  }
471
540
  }
472
- const result = prepareCustomTheme(text, existing)
473
- if (!result.ok) return { themes: existing, commit: false, value: result }
474
- return { themes: [...existing, result.theme], value: result }
541
+ if (!prepared) throw new Error('The theme could not be prepared.')
542
+ if (!prepared.ok) return { themes: existing, commit: false, value: prepared }
543
+ const theme = storedTheme(prepared.prepared, existing)
544
+ return { themes: [...existing, theme], value: { ok: true, theme } }
475
545
  },
476
546
  mutationOptions
477
547
  )
478
- return mutation.ok ? mutation.value : { ok: false, error: mutation.error }
548
+ if (!mutation.ok) return { ok: false, error: mutation.error }
549
+ return mutation.recovered && mutation.value.ok
550
+ ? { ...mutation.value, recovered: mutation.recovered }
551
+ : mutation.value
479
552
  }
480
553
 
481
554
  /** Direct host projection for inputs the canonical adapters reject. */
@@ -25,6 +25,7 @@ export {
25
25
  CUSTOM_THEME_LIBRARY_LOCK_NAME,
26
26
  CUSTOM_THEME_ATOMIC_STORAGE_UNAVAILABLE,
27
27
  CUSTOM_THEME_LIBRARY_MUTATION_FAILED,
28
+ CUSTOM_THEME_LIBRARY_RECOVERED,
28
29
  mutateCustomThemeLibrary,
29
30
  removeCustomThemeAtomically,
30
31
  } from './theme-library-mutation'
@@ -34,6 +35,7 @@ export type {
34
35
  ThemeLibraryMutation,
35
36
  ThemeLibraryMutationFailureReason,
36
37
  ThemeLibraryMutationResult,
38
+ ThemeLibraryRecoveryReason,
37
39
  } from './theme-library-mutation'
38
40
  export {
39
41
  validateThemeRegistry,
@@ -54,12 +56,11 @@ export type {
54
56
  export {
55
57
  CUSTOM_THEME_LIBRARY_STORAGE_KEY,
56
58
  CUSTOM_THEME_LIBRARY_RECOVERY_KEY,
59
+ CUSTOM_THEME_LIBRARY_PREVIOUS_RECOVERY_KEY,
57
60
  customThemeVariants,
58
61
  customThemeVariantById,
59
62
  customUiVariants,
60
63
  subscribeCustomThemes,
61
- setCustomThemes,
62
64
  readCustomThemeLibrary,
63
- removeCustomTheme,
64
65
  } from './theme-library-store'
65
66
  export type { AppearanceStorage } from './theme-library-store'
@@ -9,7 +9,7 @@
9
9
  * storage commit, storage already written is retained but stale status and
10
10
  * selection are dropped.
11
11
  */
12
- import type { CustomThemeStored } from './custom-theme-library'
12
+ import { CUSTOM_THEME_LIBRARY_RECOVERED, type CustomThemeStored } from './custom-theme-library'
13
13
 
14
14
  import type { CustomThemeImportResult } from './custom-theme-import'
15
15
 
@@ -126,7 +126,8 @@ export function createThemeFileImporter(host: ThemeFileImporterHost): ThemeFileI
126
126
  }
127
127
  host.onStatus(
128
128
  `Imported “${result.theme.name}”.` +
129
- (result.theme.notes.length > 0 ? ` ${result.theme.notes.join(' ')}` : '')
129
+ (result.theme.notes.length > 0 ? ` ${result.theme.notes.join(' ')}` : '') +
130
+ (result.recovered ? ` ${CUSTOM_THEME_LIBRARY_RECOVERED}` : '')
130
131
  )
131
132
  if (current()) host.onImported(result.theme)
132
133
  },
@@ -45,8 +45,19 @@ export type ThemeLibraryMutationFailureReason =
45
45
  | 'recovery_unavailable'
46
46
  | 'changed_during_mutation'
47
47
 
48
+ export type ThemeLibraryRecoveryReason = 'corrupt_json' | 'unsupported_record'
49
+
48
50
  export type ThemeLibraryMutationResult<T> =
49
- | { ok: true; committed: boolean; value: T }
51
+ | {
52
+ ok: true
53
+ committed: boolean
54
+ value: T
55
+ /**
56
+ * Set when this commit replaced an unreadable library. Its bytes were moved to
57
+ * `CUSTOM_THEME_LIBRARY_RECOVERY_KEY` first; show `CUSTOM_THEME_LIBRARY_RECOVERED`.
58
+ */
59
+ recovered?: ThemeLibraryRecoveryReason
60
+ }
50
61
  | { ok: false; reason: ThemeLibraryMutationFailureReason; error: string }
51
62
 
52
63
  /** Origin-wide lock name shared by all cooperating framework builds. */
@@ -62,12 +73,8 @@ export const CUSTOM_THEME_ATOMIC_STORAGE_UNAVAILABLE =
62
73
  export const CUSTOM_THEME_LIBRARY_MUTATION_FAILED =
63
74
  'The theme could not be saved. Check your storage and try again.'
64
75
 
65
- /*
66
- * Registry validation, ported from Zeron `ThemeRegistry::validate`: core text and
67
- * muted text must reach 4.5:1, the accent 3:1, on-accent 4.5:1, the terminal
68
- * foreground 4.5:1, and every chromatic ANSI slot 3:1 (slots 0 and 8 are
69
- * structural black/dim colors). Import runs it over the one variant it just built.
70
- */
76
+ export const CUSTOM_THEME_LIBRARY_RECOVERED =
77
+ 'Your saved theme library could not be fully read. The original was set aside and the library was rebuilt from what could be read.'
71
78
 
72
79
  function withIndexedDbMutationLock<T>(name: string, operation: () => T): Promise<T> {
73
80
  const factory = globalThis.indexedDB
@@ -201,10 +208,13 @@ export async function mutateCustomThemeLibrary<T>(
201
208
  try {
202
209
  let raw: string | null
203
210
  let themes: readonly CustomThemeStored[]
211
+ let recovered: ThemeLibraryRecoveryReason | undefined
204
212
  try {
205
213
  raw = storage.getItem(CUSTOM_THEME_LIBRARY_STORAGE_KEY)
206
214
  const parsed = raw ? parseLibrary(raw) : { themes: [] as CustomThemeStored[] }
207
215
  themes = parsed.themes
216
+ recovered = raw ? parsed.reason : undefined
217
+ // Only a storage refusal stops here; an earlier capture never does.
208
218
  if (raw && parsed.reason && !preserveLibrary(storage, raw, parsed.reason))
209
219
  return mutationFailure(
210
220
  'recovery_unavailable',
@@ -253,7 +263,9 @@ export async function mutateCustomThemeLibrary<T>(
253
263
 
254
264
  replaceThemes(safe)
255
265
  notifyCustomThemes()
256
- return { ok: true, committed: true, value: mutation.value }
266
+ return recovered
267
+ ? { ok: true, committed: true, value: mutation.value, recovered }
268
+ : { ok: true, committed: true, value: mutation.value }
257
269
  } finally {
258
270
  state.atomicMutationDepth = Math.max(0, (state.atomicMutationDepth ?? 1) - 1)
259
271
  }
@@ -110,6 +110,13 @@ export type ValidationIssue = Readonly<{
110
110
  message: string
111
111
  }>
112
112
 
113
+ /*
114
+ * Registry validation, ported from Zeron `ThemeRegistry::validate`: core text and
115
+ * muted text must reach 4.5:1, the accent 3:1, on-accent 4.5:1, the terminal
116
+ * foreground 4.5:1, and every chromatic ANSI slot 3:1 (slots 0 and 8 are
117
+ * structural black/dim colors). Import runs it over the one variant it just built.
118
+ */
119
+
113
120
  export function validateThemeRegistry(registry: readonly StoredThemeVariant[]): ValidationIssue[] {
114
121
  const issues: ValidationIssue[] = []
115
122
  const seen = new Set<string>()
@@ -27,6 +27,12 @@ export const CUSTOM_THEME_LIBRARY_STORAGE_KEY = 'appearance.library'
27
27
  */
28
28
  export const CUSTOM_THEME_LIBRARY_RECOVERY_KEY = 'appearance.library.recovery'
29
29
 
30
+ /**
31
+ * The one earlier capture kept when a later, different corruption is quarantined.
32
+ * Bounded to a single slot: each new capture moves the current one here.
33
+ */
34
+ export const CUSTOM_THEME_LIBRARY_PREVIOUS_RECOVERY_KEY = 'appearance.library.recovery.previous'
35
+
30
36
  export const CUSTOM_THEME_LIBRARY_VERSION = 1
31
37
 
32
38
  const CUSTOM_THEME_ID_PREFIX = 'custom-'
@@ -77,6 +83,11 @@ export function replaceThemes(themes: readonly CustomThemeStored[]): void {
77
83
  state.uiVariants = undefined
78
84
  }
79
85
 
86
+ /** The current imported-theme snapshot. Subscribers read it after every change. */
87
+ export function customThemes(): readonly CustomThemeStored[] {
88
+ return library().themes
89
+ }
90
+
80
91
  /** The imported themes' stored variants, in import order. */
81
92
  export function customThemeVariants(): readonly StoredThemeVariant[] {
82
93
  return library().themes.map((theme) => theme.variant)
@@ -143,11 +154,9 @@ function isCustomThemeId(id: string): boolean {
143
154
  }
144
155
 
145
156
  /**
146
- * Replace the in-memory imported-theme set and tell subscribers. Durable mutations
147
- * must use `mutateCustomThemeLibrary`; this deprecated synchronous API fails closed
148
- * when a storage adapter is supplied because it cannot acquire the shared lock.
149
- *
150
- * @deprecated Use `mutateCustomThemeLibrary` for persisted read/modify/write operations.
157
+ * Replace the in-memory imported-theme set and tell subscribers. Internal: the
158
+ * coordinated writer calls it after a durable commit. It fails closed when a storage
159
+ * adapter is supplied, because it cannot acquire the shared lock.
151
160
  */
152
161
  export function setCustomThemes(
153
162
  themes: readonly CustomThemeStored[],
@@ -266,17 +275,37 @@ export function parseLibrary(raw: string): {
266
275
  : { themes, reason: 'unsupported_record' }
267
276
  }
268
277
 
278
+ function capturedRaw(saved: string | null): string | undefined {
279
+ if (!saved) return undefined
280
+ try {
281
+ const capture: unknown = JSON.parse(saved)
282
+ return object(capture) && capture.schemaVersion === 1 && typeof capture.raw === 'string'
283
+ ? capture.raw
284
+ : undefined
285
+ } catch {
286
+ return undefined
287
+ }
288
+ }
289
+
290
+ /**
291
+ * Quarantine `raw` byte for byte and confirm it reads back. A different earlier
292
+ * capture moves to the previous slot instead of blocking the new one, so a second
293
+ * corruption recovers like the first. False only when storage refuses the writes.
294
+ */
269
295
  export function preserveLibrary(
270
296
  storage: AppearanceStorage,
271
297
  raw: string,
272
298
  reason: 'corrupt_json' | 'unsupported_record'
273
299
  ): boolean {
274
- const existing = storage.getItem(CUSTOM_THEME_LIBRARY_RECOVERY_KEY)
275
- if (!existing) quarantineRecord(storage, CUSTOM_THEME_LIBRARY_RECOVERY_KEY, raw, reason)
276
- const saved = storage.getItem(CUSTOM_THEME_LIBRARY_RECOVERY_KEY)
277
300
  try {
278
- const capture: unknown = saved && JSON.parse(saved)
279
- return object(capture) && capture.schemaVersion === 1 && capture.raw === raw
301
+ const existing = storage.getItem(CUSTOM_THEME_LIBRARY_RECOVERY_KEY)
302
+ if (capturedRaw(existing) !== raw) {
303
+ // Never drop the earlier capture silently: if it cannot be moved aside,
304
+ // leave it in place and report the failure.
305
+ if (existing) storage.setItem(CUSTOM_THEME_LIBRARY_PREVIOUS_RECOVERY_KEY, existing)
306
+ quarantineRecord(storage, CUSTOM_THEME_LIBRARY_RECOVERY_KEY, raw, reason)
307
+ }
308
+ return capturedRaw(storage.getItem(CUSTOM_THEME_LIBRARY_RECOVERY_KEY)) === raw
280
309
  } catch {
281
310
  return false
282
311
  }
@@ -284,7 +313,8 @@ export function preserveLibrary(
284
313
 
285
314
  /**
286
315
  * Read the stored library. A malformed document starts an empty library and
287
- * quarantines the raw bytes into the library's own recovery key, mirroring the
316
+ * quarantines the raw bytes into the library's own recovery key (the earlier
317
+ * capture, if different, moves to the previous slot), mirroring the
288
318
  * appearance-preference recovery contract; individual invalid records are dropped,
289
319
  * not fatal.
290
320
  */
@@ -362,18 +392,3 @@ function tryReadCustomThemeLibrary(
362
392
  return undefined
363
393
  }
364
394
  }
365
-
366
- /**
367
- * Synchronous legacy removal for the in-memory library. Passing storage fails closed;
368
- * use `removeCustomThemeAtomically` for persisted removals.
369
- *
370
- * @deprecated Use `removeCustomThemeAtomically` for persisted removals.
371
- */
372
- export function removeCustomTheme(id: string, storage: AppearanceStorage | undefined): boolean {
373
- if (storage) return false
374
- const themes = library().themes
375
- return setCustomThemes(
376
- themes.filter((theme) => theme.id !== id),
377
- storage
378
- )
379
- }