@adea-ai/app-framework 0.46.12 → 0.47.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 (46) hide show
  1. package/README.md +1 -1
  2. package/dist/app/application.d.ts +2 -1
  3. package/dist/app/application.js +27 -16
  4. package/dist/app/create-application.js +6 -3
  5. package/dist/appearance/appearance-host.d.ts +2 -1
  6. package/dist/appearance/appearance-host.js +28 -21
  7. package/dist/appearance/editor.js +21 -3
  8. package/dist/framework-source.json +1 -1
  9. package/dist/shell/app-shell.d.ts +1 -1
  10. package/dist/shell/app-shell.js +97 -87
  11. package/dist/shell/app-utilities.d.ts +1 -1
  12. package/dist/shell/app-utilities.js +42 -23
  13. package/dist/shell/media-query.js +12 -10
  14. package/dist/shell/navigation-drawer.d.ts +1 -1
  15. package/dist/shell/navigation-drawer.js +6 -4
  16. package/dist/shell/poll.js +9 -11
  17. package/dist/shell/settings-sections.d.ts +1 -1
  18. package/dist/views/app-about.d.ts +1 -1
  19. package/dist/views/app-about.js +1 -1
  20. package/dist/views/app-appearance.d.ts +2 -1
  21. package/dist/views/app-appearance.js +4 -4
  22. package/dist/views/app-help.d.ts +1 -1
  23. package/dist/views/app-help.js +1 -1
  24. package/dist/views/app-settings.d.ts +2 -1
  25. package/dist/views/app-settings.js +15 -10
  26. package/dist/views/appearance-surface.d.ts +1 -1
  27. package/dist/views/appearance-surface.js +116 -91
  28. package/dist/views/update-surface.d.ts +1 -1
  29. package/dist/views/update-surface.js +1 -1
  30. package/package.json +14 -13
  31. package/src/app/application.tsx +28 -32
  32. package/src/appearance/appearance-host.tsx +30 -19
  33. package/src/appearance/editor.ts +25 -3
  34. package/src/shell/app-shell.tsx +46 -37
  35. package/src/shell/app-utilities.tsx +38 -40
  36. package/src/shell/media-query.ts +15 -10
  37. package/src/shell/navigation-drawer.tsx +1 -1
  38. package/src/shell/poll.ts +9 -10
  39. package/src/shell/settings-sections.ts +1 -1
  40. package/src/views/app-appearance.tsx +4 -3
  41. package/src/views/app-settings.tsx +2 -1
  42. package/src/views/appearance-surface.tsx +46 -35
  43. package/templates/application/AGENTS.md +29 -0
  44. package/templates/application/src/web/main.tsx +2 -2
  45. package/templates/application/tsconfig.json +1 -1
  46. package/templates/application/vite.config.ts +1 -1
@@ -16,24 +16,22 @@ import { ShellTopBar } from '@adea-ai/ui/components/layout/shell-top-bar'
16
16
  import { SideRailItem, SideRailSection } from '@adea-ai/ui/components/layout/side-rail'
17
17
  import { ActionButton } from '@adea-ai/ui/components/composites/action-button'
18
18
  import { TooltipProvider } from '@adea-ai/ui/components/ui/tooltip'
19
- import { PanelLeftClose, PanelLeftIcon, PanelLeftOpen } from 'lucide-solid'
19
+ import { PanelLeftClose, PanelLeftIcon, PanelLeftOpen } from '@lucide/solid'
20
20
  import { hasEditableKeyboardTarget } from './keyboard-target'
21
21
  import { createMediaQuery, DEFAULT_NARROW_QUERY } from './media-query'
22
22
  import {
23
23
  For,
24
+ Loading,
24
25
  Show,
25
- Suspense,
26
26
  children,
27
- createComputed,
28
27
  createEffect,
29
28
  createMemo,
29
+ createRenderEffect,
30
30
  createSignal,
31
31
  lazy,
32
- onCleanup,
33
- onMount,
34
- untrack,
35
- type JSX,
32
+ onSettled,
36
33
  } from 'solid-js'
34
+ import type { JSX } from '@solidjs/web'
37
35
 
38
36
  const NavigationDrawer = lazy(() =>
39
37
  import('./navigation-drawer').then((module) => ({ default: module.NavigationDrawer }))
@@ -124,16 +122,18 @@ export function ApplicationShell(props: ApplicationShellProps) {
124
122
  // The shared callback's cleanup supplies the mode but not the detached element.
125
123
  const sidebarElements = new Map<boolean, HTMLElement>()
126
124
  const sidebarElementCallbacks = new Map<boolean, ContextualSidebarProps['onSidebarElement']>()
127
- createEffect(() => {
128
- const nextCallback = sidebarProps()?.onSidebarElement
129
- for (const [mobile, element] of sidebarElements) {
130
- const previousCallback = sidebarElementCallbacks.get(mobile)
131
- if (previousCallback === nextCallback) continue
132
- previousCallback?.(undefined, mobile)
133
- nextCallback?.(element, mobile)
134
- sidebarElementCallbacks.set(mobile, nextCallback)
125
+ createEffect(
126
+ () => sidebarProps()?.onSidebarElement,
127
+ (nextCallback) => {
128
+ for (const [mobile, element] of sidebarElements) {
129
+ const previousCallback = sidebarElementCallbacks.get(mobile)
130
+ if (previousCallback === nextCallback) continue
131
+ previousCallback?.(undefined, mobile)
132
+ nextCallback?.(element, mobile)
133
+ sidebarElementCallbacks.set(mobile, nextCallback)
134
+ }
135
135
  }
136
- })
136
+ )
137
137
  const isSidebarMobile = () => {
138
138
  const mountedMode = sidebarElementMobile()
139
139
  if (mountedMode !== undefined) return mountedMode
@@ -142,36 +142,45 @@ export function ApplicationShell(props: ApplicationShellProps) {
142
142
  if (mode === 'desktop') return false
143
143
  return sidebarMobile()
144
144
  }
145
- const restoreSidebarFocus = (sidebar: HTMLElement | undefined) => {
145
+ const restoreSidebarFocus = (
146
+ sidebar: HTMLElement | undefined,
147
+ current: ContextualSidebarProps | undefined
148
+ ) => {
146
149
  const active = sidebar?.ownerDocument.activeElement
147
150
  if (
148
- !sidebarProps() ||
151
+ !current ||
149
152
  sidebar?.dataset.open !== 'true' ||
150
153
  !sidebar.isConnected ||
151
154
  !active ||
152
155
  !sidebar.contains(active)
153
156
  )
154
157
  return
155
- const restoreFocusRef = sidebarProps()?.restoreFocusRef
158
+ const restoreFocusRef = current.restoreFocusRef
156
159
  const target = restoreFocusRef ? restoreFocusRef() : sidebarToggle
157
160
  if (target?.isConnected) target.focus({ preventScroll: true })
158
161
  }
162
+ // A forced switch to mobile hides the desktop sidebar, so focus inside it goes back to the
163
+ // toggle first. This runs in the render phase, before the desktop sidebar is hidden; a user
164
+ // effect would run after it, when the focused element has already left the page.
159
165
  let requestedModeInitialized = false
160
166
  let previousRequestedMode: ReturnType<typeof getSidebarResponsiveMode>
161
- createComputed(() => {
162
- const next = getSidebarResponsiveMode(sidebarProps())
163
- const shouldRestore =
164
- requestedModeInitialized && next === 'mobile' && previousRequestedMode !== 'mobile'
165
- previousRequestedMode = next
166
- requestedModeInitialized = true
167
- if (shouldRestore) untrack(() => restoreSidebarFocus(sidebarElements.get(false)))
168
- })
167
+ createRenderEffect(
168
+ () => sidebarProps(),
169
+ (current) => {
170
+ const next = getSidebarResponsiveMode(current)
171
+ const shouldRestore =
172
+ requestedModeInitialized && next === 'mobile' && previousRequestedMode !== 'mobile'
173
+ previousRequestedMode = next
174
+ requestedModeInitialized = true
175
+ if (shouldRestore) restoreSidebarFocus(sidebarElements.get(false), current)
176
+ }
177
+ )
169
178
  const handleSidebarModeTransition: NonNullable<
170
179
  ContextualSidebarProps['onResponsiveModeTransition']
171
180
  > = (event) => {
172
181
  sidebarProps()?.onResponsiveModeTransition?.(event)
173
182
  if (event.phase === 'before' && event.from === 'desktop' && event.to === 'mobile')
174
- restoreSidebarFocus(event.desktopSidebar)
183
+ restoreSidebarFocus(event.desktopSidebar, sidebarProps())
175
184
  }
176
185
  const handleSidebarElement: NonNullable<ContextualSidebarProps['onSidebarElement']> = (
177
186
  element,
@@ -196,8 +205,8 @@ export function ApplicationShell(props: ApplicationShellProps) {
196
205
  // The drawer mounts (and its chunk loads) the first time the window is narrow, and
197
206
  // stays mounted after that so its close animation and focus return keep working.
198
207
  const [drawerMounted, setDrawerMounted] = createSignal(false)
199
- createEffect(() => {
200
- if (narrow()) setDrawerMounted(true)
208
+ createEffect(narrow, (isNarrow) => {
209
+ if (isNarrow) setDrawerMounted(true)
201
210
  else setDrawerOpen(false)
202
211
  })
203
212
  const leading = () => sidebarProps() ?? props.pane
@@ -240,13 +249,13 @@ export function ApplicationShell(props: ApplicationShellProps) {
240
249
  event.preventDefault()
241
250
  if (!event.repeat) props.onSearch()
242
251
  }
243
- onMount(() => {
252
+ onSettled(() => {
244
253
  window.addEventListener('keydown', handleSearch)
245
254
  window.addEventListener('keydown', handleToggle)
246
- onCleanup(() => {
255
+ return () => {
247
256
  window.removeEventListener('keydown', handleSearch)
248
257
  window.removeEventListener('keydown', handleToggle)
249
- })
258
+ }
250
259
  })
251
260
  // The rail slot resolves once, and only while the rail shows: reading a JSX prop in both a
252
261
  // `when` and the body would build the app's rail twice.
@@ -265,7 +274,7 @@ export function ApplicationShell(props: ApplicationShellProps) {
265
274
  label={item.label}
266
275
  aria-label={item.label}
267
276
  active={props.activeDestination === item.id}
268
- aria-pressed={props.activeDestination === item.id}
277
+ aria-pressed={props.activeDestination === item.id ? 'true' : 'false'}
269
278
  onClick={() => props.onNavigate(item.id)}
270
279
  >
271
280
  {item.icon}
@@ -304,7 +313,7 @@ export function ApplicationShell(props: ApplicationShellProps) {
304
313
  variant="toolbar"
305
314
  tooltip={toggleLabel()}
306
315
  aria-label={toggleLabel()}
307
- aria-expanded={expanded()}
316
+ aria-expanded={expanded() ? 'true' : 'false'}
308
317
  aria-controls={narrow() || sidebarProps() ? undefined : props.pane?.id}
309
318
  onClick={toggle}
310
319
  >
@@ -380,7 +389,7 @@ export function ApplicationShell(props: ApplicationShellProps) {
380
389
  </AppShell>
381
390
  <Show when={drawerMounted() && props.drawer}>
382
391
  {(drawer) => (
383
- <Suspense>
392
+ <Loading>
384
393
  <NavigationDrawer
385
394
  name={props.name}
386
395
  open={narrow() && drawerOpen()}
@@ -389,7 +398,7 @@ export function ApplicationShell(props: ApplicationShellProps) {
389
398
  >
390
399
  {drawer()(() => setDrawerOpen(false))}
391
400
  </NavigationDrawer>
392
- </Suspense>
401
+ </Loading>
393
402
  )}
394
403
  </Show>
395
404
  </div>
@@ -5,19 +5,9 @@ import {
5
5
  } from '@adea-ai/ui/components/composites/account-menu'
6
6
  import type { UpdateAdapter, UpdateState } from '@adea-ai/ui/components/composites/update-dialog'
7
7
  import { ThemeProvider, type ThemeProviderProps } from '@adea-ai/ui/components/theme/lazy'
8
- import { Palette } from 'lucide-solid'
9
- import {
10
- createEffect,
11
- createMemo,
12
- createSignal,
13
- lazy,
14
- on,
15
- onCleanup,
16
- onMount,
17
- Show,
18
- Suspense,
19
- type JSX,
20
- } from 'solid-js'
8
+ import { Palette } from '@lucide/solid'
9
+ import { createEffect, createMemo, createSignal, lazy, Loading, onSettled, Show } from 'solid-js'
10
+ import type { JSX } from '@solidjs/web'
21
11
  import { DEFAULT_SETTINGS_KEYSHORTCUTS, type HelpLink, type HelpShortcut } from './help-shortcuts'
22
12
  import { matchesSettingsKeyshortcuts, parseSettingsKeyshortcuts } from './settings-shortcuts'
23
13
  import {
@@ -198,7 +188,15 @@ function placeAppearance(
198
188
  /** Shared account menu and application dialogs. Mount inside ApplicationThemeProvider. */
199
189
  export function ApplicationUtilities(props: ApplicationUtilitiesProps) {
200
190
  type Surface = 'appearance' | 'about' | 'updates' | 'settings' | 'help'
201
- const [dialog, setDialog] = createSignal<Surface>()
191
+ const [dialog, setDialogSignal] = createSignal<Surface>()
192
+ // The open surface as of the last write. Solid 2 shows a write to readers on the next
193
+ // flush, and the controlled-open effect below must act on the surface a handler in the
194
+ // same frame just chose, without re-running whenever it changes.
195
+ let currentDialog: Surface | undefined
196
+ const setDialog = (value: Surface | undefined) => {
197
+ currentDialog = value
198
+ setDialogSignal(() => value)
199
+ }
202
200
  const [mounted, setMounted] = createSignal<ReadonlySet<Surface>>(new Set())
203
201
  const [localSection, setLocalSection] = createSignal<string>()
204
202
  let opener: HTMLElement | undefined
@@ -247,10 +245,11 @@ export function ApplicationUtilities(props: ApplicationUtilitiesProps) {
247
245
  () => props.updater ?? browserUpdateAdapter(props.identity.version)
248
246
  )
249
247
  const markMounted = (value: Surface) => {
250
- if (!mounted().has(value)) setMounted((current) => new Set(current).add(value))
248
+ setMounted((current) => (current.has(value) ? current : new Set(current).add(value)))
251
249
  }
252
250
  const show = (value: Surface | undefined) => {
253
- const wasOpen = settingsOpen()
251
+ const wasOpen =
252
+ props.settings?.open !== undefined ? props.settings.open : currentDialog === 'settings'
254
253
  if (value) markMounted(value)
255
254
  setDialog(value)
256
255
  const isOpen = value === 'settings'
@@ -280,26 +279,25 @@ export function ApplicationUtilities(props: ApplicationUtilitiesProps) {
280
279
  }
281
280
  // A controlled open from the app's own store mounts the dialog it opens.
282
281
  createEffect(
283
- on(
284
- () => props.settings?.open,
285
- (value) => {
286
- if (value === false && dialog() === 'settings') setDialog(undefined)
287
- if (!value || !settingsSections()) return
288
- if (!opener) opener = (document.activeElement as HTMLElement | null) ?? undefined
289
- markMounted('settings')
290
- if (dialog() !== 'settings') setDialog('settings')
291
- }
292
- )
293
- )
294
- props.commands?.(
295
- Object.freeze({
296
- openSettings: (id?: string) => openSettings(id),
297
- openAppearance: () => openAppearance(),
298
- openAbout: () => open('about'),
299
- openHelp: () => open('help'),
300
- openUpdates: () => openUpdates(),
301
- })
282
+ () => ({ open: props.settings?.open, ready: Boolean(settingsSections()) }),
283
+ ({ open: value, ready }) => {
284
+ if (value === false && currentDialog === 'settings') setDialog(undefined)
285
+ if (!value || !ready) return
286
+ if (!opener) opener = (document.activeElement as HTMLElement | null) ?? undefined
287
+ markMounted('settings')
288
+ if (currentDialog !== 'settings') setDialog('settings')
289
+ }
302
290
  )
291
+ const commands: ApplicationCommands = Object.freeze({
292
+ openSettings: (id?: string) => openSettings(id),
293
+ openAppearance: () => openAppearance(),
294
+ openAbout: () => open('about'),
295
+ openHelp: () => open('help'),
296
+ openUpdates: () => openUpdates(),
297
+ })
298
+ // Hand the commands over in an owned scope, so a receiver can register `onCleanup` (to
299
+ // disconnect a native menu channel, say), and again if the app passes a new receiver.
300
+ createMemo(() => props.commands?.(commands))
303
301
  const settingsKeyshortcuts = createMemo(() => {
304
302
  const value = props.accountMenu?.settingsKeyshortcuts ?? DEFAULT_SETTINGS_KEYSHORTCUTS
305
303
  return { value, chords: parseSettingsKeyshortcuts(value) }
@@ -325,14 +323,14 @@ export function ApplicationUtilities(props: ApplicationUtilitiesProps) {
325
323
  const id = settingsSectionFromHash(window.location.hash, sections, defaultSection())
326
324
  if (id) openSettings(id)
327
325
  }
328
- onMount(() => {
326
+ onSettled(() => {
329
327
  onHash()
330
328
  window.addEventListener('keydown', onKeyDown)
331
329
  window.addEventListener('hashchange', onHash)
332
- onCleanup(() => {
330
+ return () => {
333
331
  window.removeEventListener('keydown', onKeyDown)
334
332
  window.removeEventListener('hashchange', onHash)
335
- })
333
+ }
336
334
  })
337
335
  const close = () => show(undefined)
338
336
  // Menu inputs as separate memos: an app that passes `accountMenu` as an inline object (say,
@@ -396,7 +394,7 @@ export function ApplicationUtilities(props: ApplicationUtilitiesProps) {
396
394
  />
397
395
  {/* A dialog loading here must not draw text in the rail under the avatar: the wait is
398
396
  announced to screen readers only, and the dialog appears in place once it loads. */}
399
- <Suspense
397
+ <Loading
400
398
  fallback={
401
399
  dialog() ? (
402
400
  <span class="visually-hidden" role="status">
@@ -468,7 +466,7 @@ export function ApplicationUtilities(props: ApplicationUtilitiesProps) {
468
466
  restoreFocusRef={() => opener}
469
467
  />
470
468
  </Show>
471
- </Suspense>
469
+ </Loading>
472
470
  </>
473
471
  )
474
472
  }
@@ -1,4 +1,4 @@
1
- import { createComputed, createSignal, onCleanup } from 'solid-js'
1
+ import { createEffect, createSignal } from 'solid-js'
2
2
 
3
3
  /** When the application shell counts a window as narrow. */
4
4
  export const DEFAULT_NARROW_QUERY = '(max-width: 799px)'
@@ -15,7 +15,7 @@ const shared = new Map<string, SharedQuery>()
15
15
 
16
16
  const supported = () => typeof window !== 'undefined' && typeof window.matchMedia === 'function'
17
17
 
18
- function subscribe(query: string, subscriber: (matches: boolean) => void): () => void {
18
+ function entryFor(query: string): SharedQuery {
19
19
  let entry = shared.get(query)
20
20
  if (!entry) {
21
21
  const list = window.matchMedia(query)
@@ -28,7 +28,11 @@ function subscribe(query: string, subscriber: (matches: boolean) => void): () =>
28
28
  entry = { list, subscribers, stop: () => list.removeEventListener('change', notify) }
29
29
  shared.set(query, entry)
30
30
  }
31
- const current = entry
31
+ return entry
32
+ }
33
+
34
+ function subscribe(query: string, subscriber: (matches: boolean) => void): () => void {
35
+ const current = entryFor(query)
32
36
  current.subscribers.add(subscriber)
33
37
  subscriber(current.list.matches)
34
38
  return () => {
@@ -47,14 +51,15 @@ function subscribe(query: string, subscriber: (matches: boolean) => void): () =>
47
51
  */
48
52
  export function createMediaQuery(query: string | (() => string | undefined)): () => boolean {
49
53
  const text = typeof query === 'function' ? query : () => query
50
- const [matches, setMatches] = createSignal(false)
51
- createComputed(() => {
54
+ // The derived form answers synchronously from the window whenever the query changes, so
55
+ // the first render already has the right layout; change events then write over it.
56
+ const [matches, setMatches] = createSignal(() => {
52
57
  const value = text()
53
- if (!value || !supported()) {
54
- setMatches(false)
55
- return
56
- }
57
- onCleanup(subscribe(value, setMatches))
58
+ return Boolean(value) && supported() && entryFor(value!).list.matches
59
+ })
60
+ createEffect(text, (value) => {
61
+ if (!value || !supported()) return
62
+ return subscribe(value, setMatches)
58
63
  })
59
64
  return matches
60
65
  }
@@ -1,5 +1,5 @@
1
1
  import { Sheet, SheetContent, SheetHeader, SheetTitle } from '@adea-ai/ui/components/ui/sheet'
2
- import type { JSX } from 'solid-js'
2
+ import type { JSX } from '@solidjs/web'
3
3
 
4
4
  /**
5
5
  * The narrow-window navigation drawer. The shell loads it the first time the window is
package/src/shell/poll.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { createEffect, getOwner, onCleanup, untrack } from 'solid-js'
1
+ import { createEffect, getOwner, onSettled } from 'solid-js'
2
2
 
3
3
  export type PollOptions = Readonly<{
4
4
  /** Time from one run settling to the next starting. */
@@ -99,18 +99,17 @@ export function createPoll(options: PollOptions): Poll {
99
99
  }
100
100
 
101
101
  if (options.enabled) {
102
- const enabled = options.enabled
103
- createEffect(() => {
104
- if (!enabled()) return
105
- // A tick's own reads must not restart the poll.
106
- untrack(start)
107
- onCleanup(stop)
102
+ // The apply phase is untracked, so a tick's own reads never restart the poll.
103
+ createEffect(options.enabled, (enabled) => {
104
+ if (!enabled) return
105
+ start()
106
+ return stop
108
107
  })
109
108
  } else if (getOwner()) {
110
109
  // Start after the owner's setup, like an effect, so the first tick sees settled state.
111
- createEffect(() => {
112
- untrack(start)
113
- onCleanup(stop)
110
+ onSettled(() => {
111
+ start()
112
+ return stop
114
113
  })
115
114
  } else {
116
115
  start()
@@ -1,4 +1,4 @@
1
- import type { JSX } from 'solid-js'
1
+ import type { JSX } from '@solidjs/web'
2
2
 
3
3
  /** One settings destination. The framework owns layout and navigation; the app owns the panel. */
4
4
  export type ApplicationSettingsSection = Readonly<{
@@ -1,5 +1,6 @@
1
1
  import { ModalDialog } from '@adea-ai/ui/components/ui/modal-dialog'
2
- import { lazy, Show, Suspense, type Accessor, type JSX } from 'solid-js'
2
+ import { lazy, Loading, Show, type Accessor } from 'solid-js'
3
+ import type { JSX } from '@solidjs/web'
3
4
 
4
5
  const AppearancePanel = lazy(() =>
5
6
  import('@adea-ai/ui/components/theme').then((module) => ({ default: module.AppearancePanel }))
@@ -24,9 +25,9 @@ export function ApplicationAppearance(props: ApplicationAppearanceProps) {
24
25
  size="settings"
25
26
  restoreFocusRef={props.restoreFocusRef}
26
27
  >
27
- <Suspense fallback={<span role="status">Loading appearance…</span>}>
28
+ <Loading fallback={<span role="status">Loading appearance…</span>}>
28
29
  <Show when={props.open}>{props.panel ?? <AppearancePanel />}</Show>
29
- </Suspense>
30
+ </Loading>
30
31
  </ModalDialog>
31
32
  )
32
33
  }
@@ -2,7 +2,8 @@ import { SettingsLayout } from '@adea-ai/ui/components/composites/settings'
2
2
  import { ModalDialog } from '@adea-ai/ui/components/ui/modal-dialog'
3
3
  import { TabsContent } from '@adea-ai/ui/components/ui/tabs'
4
4
  import { Text } from '@adea-ai/ui/components/ui/typography'
5
- import { createMemo, For, Show, untrack, type Accessor, type JSX } from 'solid-js'
5
+ import { createMemo, For, Show, untrack, type Accessor } from 'solid-js'
6
+ import type { JSX } from '@solidjs/web'
6
7
 
7
8
  import { settingsGroups, type ApplicationSettingsSection } from '../shell/settings-sections'
8
9
 
@@ -36,18 +36,17 @@ import { Input } from '@adea-ai/ui/components/ui/input'
36
36
  import { ModalDialog } from '@adea-ai/ui/components/ui/modal-dialog'
37
37
  import { Heading } from '@adea-ai/ui/components/ui/typography'
38
38
  import {
39
- batch,
40
39
  createEffect,
41
40
  createMemo,
42
41
  createSignal,
43
42
  For,
44
43
  onCleanup,
45
- onMount,
44
+ onSettled,
46
45
  Show,
47
46
  untrack,
48
- type JSX,
49
47
  } from 'solid-js'
50
- import { MonitorCog } from 'lucide-solid'
48
+ import type { JSX } from '@solidjs/web'
49
+ import { MonitorCog } from '@lucide/solid'
51
50
  import { themeAccentsForRecords } from '@adea-ai/ui/lib/theme-projection'
52
51
 
53
52
  import { draftVariants } from '../appearance/composition'
@@ -105,19 +104,21 @@ function AppearanceHost(props: { popover?: AppearanceControlProps }) {
105
104
  // instead of on the first selection. A mounted but closed popover does not
106
105
  // need it yet; the embedded panel is already visible when mounted.
107
106
  let catalogueRequested = false
108
- createEffect(() => {
109
- if (!catalogueRequested && (!props.popover || props.popover.open)) {
110
- catalogueRequested = true
111
- void appearance.loadCatalogue?.()
107
+ createEffect(
108
+ () => !props.popover || props.popover.open,
109
+ (visible) => {
110
+ if (!catalogueRequested && visible) {
111
+ catalogueRequested = true
112
+ void appearance.loadCatalogue?.()
113
+ }
112
114
  }
113
- })
115
+ )
114
116
  // Mirror the glass choice to the native window whenever it changes (the
115
117
  // desktop host registers the transport; everywhere else this is a no-op).
116
118
  // Through a memo: each mirror is a persisted host write, and accent, theme and
117
119
  // font edits leave the surface as it was.
118
120
  const draftSurface = createMemo(() => editor.draft().surface)
119
- createEffect(() => {
120
- const surface = draftSurface()
121
+ createEffect(draftSurface, (surface) => {
121
122
  mirrorWindowSurface(surface === 'translucent' ? 'theme' : surface)
122
123
  })
123
124
  const [customAccent, setCustomAccent] = createSignal('')
@@ -131,11 +132,11 @@ function AppearanceHost(props: { popover?: AppearanceControlProps }) {
131
132
  // Imported themes: refreshed through the registry subscription so the
132
133
  // picker and this dialog track imports and removals without prop drilling.
133
134
  const [library, setLibrary] = createSignal(readCustomThemeLibrary(defaultPreferenceStorage()))
134
- onMount(() => {
135
+ onSettled(() => {
135
136
  setLibrary(readCustomThemeLibrary(defaultPreferenceStorage()))
136
137
  // Every notification follows an update of the shared snapshot (a commit, or a
137
138
  // read that found new storage), so take it instead of re-reading storage.
138
- onCleanup(subscribeCustomThemes(() => setLibrary(customThemes())))
139
+ return subscribeCustomThemes(() => setLibrary(customThemes()))
139
140
  })
140
141
  // Imported records are a projection of the library, not of the draft. Keep
141
142
  // the catalogue stable while controls update; imports and removals invalidate it.
@@ -155,7 +156,6 @@ function AppearanceHost(props: { popover?: AppearanceControlProps }) {
155
156
  const draftAccent = createMemo(() => editor.draft().accent)
156
157
  const previewPair = createMemo(
157
158
  () => ({ lightThemeId: lightThemeId(), darkThemeId: darkThemeId() }),
158
- undefined,
159
159
  {
160
160
  equals: (left, right) =>
161
161
  left.lightThemeId === right.lightThemeId && left.darkThemeId === right.darkThemeId,
@@ -243,8 +243,14 @@ function AppearanceHost(props: { popover?: AppearanceControlProps }) {
243
243
  })
244
244
 
245
245
  const sampleVariant = () => {
246
- const variants = miniatures()
247
- const mode = editor.draft().mode
246
+ // From the editor's current draft, not the `miniatures` memo: a memo shows a write only
247
+ // after the next flush, and this runs in the same handler that just changed the theme.
248
+ const draft = editor.draft()
249
+ const variants = draftVariants({
250
+ lightThemeId: draft.lightThemeId,
251
+ darkThemeId: draft.darkThemeId,
252
+ })
253
+ const mode = draft.mode
248
254
  if (mode === 'light') return variants.light
249
255
  if (mode === 'dark') return variants.dark
250
256
  // The document may still show the prior preview during a batched switch
@@ -300,21 +306,19 @@ function AppearanceHost(props: { popover?: AppearanceControlProps }) {
300
306
  setDraft({ accent: validation.value })
301
307
  }
302
308
 
303
- const onChange = (patch: Partial<AppearanceDraft>) =>
304
- batch(() => {
305
- const { accent, surface, ...rest } = patch
306
- const otherChanges: Partial<AppearancePreferencesV2> = {
307
- ...rest,
308
- ...(surface === undefined
309
- ? {}
310
- : { surface: surface === 'theme' ? 'translucent' : surface }),
311
- }
312
- if (accent !== undefined) {
313
- setAccent(accent, otherChanges)
314
- return
315
- }
316
- setDraft(otherChanges)
317
- })
309
+ // Solid 2 batches every write in a handler, so the combined patch lands as one update.
310
+ const onChange = (patch: Partial<AppearanceDraft>) => {
311
+ const { accent, surface, ...rest } = patch
312
+ const otherChanges: Partial<AppearancePreferencesV2> = {
313
+ ...rest,
314
+ ...(surface === undefined ? {} : { surface: surface === 'theme' ? 'translucent' : surface }),
315
+ }
316
+ if (accent !== undefined) {
317
+ setAccent(accent, otherChanges)
318
+ return
319
+ }
320
+ setDraft(otherChanges)
321
+ }
318
322
 
319
323
  const save = () => {
320
324
  // The embedded section's published action stays disabled until the draft
@@ -353,9 +357,12 @@ function AppearanceHost(props: { popover?: AppearanceControlProps }) {
353
357
  closeLibrary()
354
358
  }
355
359
 
356
- onMount(openDraft)
357
-
358
- onCleanup(revertDraft)
360
+ // Open the draft once the host has settled, and restore the committed appearance when the
361
+ // host goes away without a save.
362
+ onSettled(() => {
363
+ openDraft()
364
+ return revertDraft
365
+ })
359
366
 
360
367
  const editorProps: AppearanceEditorProps = {
361
368
  get draft() {
@@ -492,7 +499,11 @@ function AppearanceHost(props: { popover?: AppearanceControlProps }) {
492
499
  Import a theme file (.json)
493
500
  </Button>
494
501
  <Show when={importStatus()}>
495
- <p class="text-sm text-muted-foreground" role="status" aria-busy={importPending()}>
502
+ <p
503
+ class="text-sm text-muted-foreground"
504
+ role="status"
505
+ aria-busy={importPending() ? 'true' : 'false'}
506
+ >
496
507
  {importStatus()}
497
508
  </p>
498
509
  </Show>
@@ -0,0 +1,29 @@
1
+ # Agent guide
2
+
3
+ This app is built on `@adea-ai/app-framework` and the Adea design system
4
+ `@adea-ai/ui`. Read the [README](README.md) for its layout, commands and release
5
+ setup.
6
+
7
+ ## Solid 2 and ui-sdk
8
+
9
+ The app is Solid 2 (`solid-js` and `@solidjs/web` 2.x). Before writing reactive
10
+ code, read `node_modules/solid-js/skills/solid-2.0/SKILL.md`: the 1.x APIs
11
+ (one-argument `createEffect`, `splitProps`, `onMount`, `classList`, `solid-js/web`,
12
+ `Context.Provider`) do not exist any more.
13
+
14
+ The behaviour primitives under `@adea-ai/ui` come from ui-sdk (`@ui-sdk/solid` over
15
+ `@ui-sdk/core`). Before using ui-sdk, follow the ui-sdk skill if it's installed, and
16
+ read `node_modules/@ui-sdk/solid/docs/llms.txt`. To build a new component, also
17
+ search `node_modules/@ui-sdk/solid/docs/core.md` by heading, and read
18
+ `rendering.md` next to it.
19
+
20
+ ## Commands
21
+
22
+ ```sh
23
+ bun install
24
+ bun run format:check
25
+ bun run lint
26
+ bun run typecheck
27
+ bun run test
28
+ bun run build:web
29
+ ```
@@ -1,6 +1,6 @@
1
1
  import { createSignal, lazy, onCleanup } from 'solid-js'
2
- import { render } from 'solid-js/web'
3
- import { House } from 'lucide-solid'
2
+ import { render } from '@solidjs/web'
3
+ import { House } from '@lucide/solid'
4
4
  import { Application, defineApplication } from '@adea-ai/app-framework/application'
5
5
  import { ThemeProvider } from '@adea-ai/app-framework/appearance-host'
6
6
  import { connectApplicationCommands } from '@adea-ai/app-framework/application-command-client'
@@ -4,7 +4,7 @@
4
4
  "module": "Preserve",
5
5
  "moduleResolution": "Bundler",
6
6
  "jsx": "preserve",
7
- "jsxImportSource": "solid-js",
7
+ "jsxImportSource": "@solidjs/web",
8
8
  "types": ["bun", "vite/client", "@adea-ai/app-framework/electrobun-types"],
9
9
  "strict": true,
10
10
  "skipLibCheck": true,
@@ -3,7 +3,7 @@ import { existsSync } from 'node:fs'
3
3
  import { readFile, writeFile } from 'node:fs/promises'
4
4
  import { join, resolve } from 'node:path'
5
5
  import { defineConfig, type Plugin } from 'vite'
6
- import solid from 'vite-plugin-solid'
6
+ import solid from '@solidjs/vite-plugin'
7
7
  import tailwind from '@tailwindcss/vite'
8
8
  import { applicationVersion } from './scripts/app-version'
9
9
  import {