@sirenodeck/sirenodeck 0.2.9 → 0.4.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 (65) hide show
  1. package/dist/main.mjs +1118 -624
  2. package/dist/{windows-CRWdUgCn.mjs → windows-BCvfQ3PA.mjs} +4 -4
  3. package/frontend/src/App.tsx +3 -0
  4. package/frontend/src/components/Deck.tsx +13 -2
  5. package/package.json +10 -1
  6. package/src/addon/api.ts +24 -1
  7. package/src/addon/data-directory.ts +52 -0
  8. package/src/api/protocol-internal.ts +1 -0
  9. package/src/builtin-addons/coding-agents/global/backend.ts +15 -1
  10. package/src/builtin-addons/index.ts +0 -1
  11. package/src/builtin-addons/internal-settings/backend.ts +1 -1
  12. package/src/builtin-addons/internal-settings/buttons/brightness/common/frontend.tsx +14 -3
  13. package/src/builtin-addons/internal-settings/buttons/brightness-compact/frontend.tsx +6 -0
  14. package/src/builtin-addons/internal-settings/index.ts +15 -0
  15. package/src/builtin-addons/media/backend.ts +21 -0
  16. package/src/builtin-addons/register-builtins.ts +0 -3
  17. package/src/builtin-addons/system-status/README.md +1 -1
  18. package/src/builtin-addons/system-status/domain/display-metrics.ts +1 -1
  19. package/src/builtin-addons/system-status/manifest.ts +1 -1
  20. package/src/cli/commands/addon-decks.ts +1 -0
  21. package/src/cli/commands/addon-setup-config.ts +85 -0
  22. package/src/cli/commands/addon-setup.ts +134 -0
  23. package/src/cli/commands/emulator-mode.ts +2 -1
  24. package/src/cli/commands/run.ts +53 -11
  25. package/src/cli/commands/service-manager.ts +3 -5
  26. package/src/cli/commands/start.ts +14 -81
  27. package/src/cli/commands/stop.ts +4 -0
  28. package/src/cli/index.ts +2 -0
  29. package/src/config/environment.ts +44 -0
  30. package/src/config/loader.ts +17 -1
  31. package/src/config/schemas.ts +2 -1
  32. package/src/config/validation.ts +5 -1
  33. package/src/deck/addon-handler-bridge.ts +105 -6
  34. package/src/deck/addon-settings.ts +94 -0
  35. package/src/deck/deck-config.ts +1 -0
  36. package/src/deck/inject-config-ui-button.ts +25 -14
  37. package/src/deck/runtime/runtime.ts +175 -3
  38. package/src/deck/system-back-injection.ts +2 -0
  39. package/src/deck/system-buttons/registry.tsx +1 -0
  40. package/src/deck/system-buttons/types.ts +1 -0
  41. package/src/system/credentials/native.ts +74 -0
  42. package/src/system/credentials/store.ts +77 -0
  43. package/src/system/providers/notification/windows.ts +4 -4
  44. package/src/themes/default/sirenodeck.json +1 -0
  45. package/src/themes/light/sirenodeck.json +1 -0
  46. package/src/themes/manifest.ts +1 -0
  47. package/src/ui/primitives/Chip.tsx +1 -0
  48. package/src/ui/primitives/StatusIndicator.tsx +36 -0
  49. package/src/ui/primitives/index.ts +1 -0
  50. package/src/ui/surfaces/BinaryToggleSurface.tsx +52 -0
  51. package/src/ui/surfaces/LoadingSurface.tsx +34 -0
  52. package/src/ui/surfaces/index.ts +2 -0
  53. package/src/builtin-addons/brightness/README.md +0 -51
  54. package/src/builtin-addons/brightness/buttons/brightness/backend.ts +0 -13
  55. package/src/builtin-addons/brightness/buttons/brightness/config.ts +0 -20
  56. package/src/builtin-addons/brightness/buttons/brightness/frontend.tsx +0 -50
  57. package/src/builtin-addons/brightness/domain/macos.ts +0 -46
  58. package/src/builtin-addons/brightness/index.d.ts +0 -5
  59. package/src/builtin-addons/brightness/index.ts +0 -20
  60. package/src/builtin-addons/brightness/poller.ts +0 -27
  61. package/src/builtin-addons/brightness/sirenodeck.json +0 -6
  62. /package/src/builtin-addons/{brightness/providers → internal-settings/brightness-providers}/darwin.ts +0 -0
  63. /package/src/builtin-addons/{brightness/providers → internal-settings/brightness-providers}/index.ts +0 -0
  64. /package/src/builtin-addons/{brightness/providers → internal-settings/brightness-providers}/linux.ts +0 -0
  65. /package/src/builtin-addons/{brightness/providers → internal-settings/brightness-providers}/windows.ts +0 -0
@@ -19,6 +19,12 @@ import type { Methods } from "@/deck/methods"
19
19
  import type { Runtime, RuntimeDeck } from "@/deck/runtime"
20
20
  import type { StatePublisher } from "@/render/state-publisher"
21
21
  import type { WsBridge } from "@/render/ws-bridge"
22
+ import {
23
+ scopeCredentials,
24
+ type CredentialBackend,
25
+ } from "@/system/credentials/store"
26
+ import { createNativeCredentialBackend } from "@/system/credentials/native"
27
+ import { createAddonDataDirectory } from "@/addon/data-directory"
22
28
 
23
29
  export interface BridgeAddonServicesParams {
24
30
  readonly runtime: Runtime
@@ -36,6 +42,11 @@ export interface BridgeAddonServicesParams {
36
42
  readonly statePublisher: Pick<StatePublisher, "registerChannel">
37
43
  readonly bridge: Pick<WsBridge, "broadcast" | "registerCacheablePoller">
38
44
  readonly methods: Methods
45
+ /** Backend-only configuration keyed by the loaded addon manifest name. */
46
+ readonly addonServiceConfigs?: ReadonlyMap<string, unknown>
47
+ readonly credentialBackend?: CredentialBackend
48
+ /** Override the host application-data root, primarily for tests. */
49
+ readonly addonDataRoot?: string
39
50
  /** Optional host callback that re-materializes addon decks (dynamic decks). */
40
51
  readonly requestDeckRebuild?: () => void
41
52
  }
@@ -106,6 +117,8 @@ export const bridgeAddonServices = async (
106
117
  statePublisher,
107
118
  bridge,
108
119
  methods,
120
+ addonServiceConfigs,
121
+ credentialBackend = createNativeCredentialBackend(),
109
122
  requestDeckRebuild,
110
123
  } = params
111
124
  const logger = params.logger.child({ component: "addon-handler" })
@@ -129,6 +142,7 @@ export const bridgeAddonServices = async (
129
142
 
130
143
  const addonModules = new Map<string, AddonModule>()
131
144
  const addonGlobalServices = new Map<string, AddonGlobalService>()
145
+ const addonDataDirectories = new Map<string, () => Promise<string>>()
132
146
  const addonMethods = new Map<
133
147
  string,
134
148
  Readonly<Record<string, AddonServiceMethod>>
@@ -179,6 +193,16 @@ export const bridgeAddonServices = async (
179
193
  }
180
194
 
181
195
  for (const [addonName, globalService] of addonGlobalServices) {
196
+ const getDataDirectory = createAddonDataDirectory(
197
+ addonName,
198
+ params.addonDataRoot,
199
+ )
200
+ addonDataDirectories.set(addonName, getDataDirectory)
201
+ const interruptions = new Set<() => void>()
202
+ abortController.signal.addEventListener("abort", () => {
203
+ for (const release of interruptions) release()
204
+ interruptions.clear()
205
+ })
182
206
  const primaryChannel = globalService.pollers?.[0]?.channel
183
207
  const pollersById = new Map<string, AddonGlobalPoller>()
184
208
  for (const poller of globalService.pollers ?? []) {
@@ -186,6 +210,37 @@ export const bridgeAddonServices = async (
186
210
  }
187
211
 
188
212
  const ctx: AddonServiceContext = {
213
+ getDataDirectory,
214
+ interruptDeck: (deckId, options) => {
215
+ if (abortController.signal.aborted) return null
216
+ const release = runtime.interruptDeck(deckId, options)
217
+ if (release === null) return null
218
+ const ownedRelease = () => {
219
+ interruptions.delete(ownedRelease)
220
+ release()
221
+ }
222
+ interruptions.add(ownedRelease)
223
+ return ownedRelease
224
+ },
225
+ showModal: (deckId, options) => {
226
+ if (abortController.signal.aborted) return null
227
+ let ownedRelease: () => void
228
+ const release = runtime.showModal(deckId, {
229
+ onOk: async () => {
230
+ interruptions.delete(ownedRelease)
231
+ if (abortController.signal.aborted) return
232
+ await options?.onOk?.()
233
+ },
234
+ })
235
+ if (release === null) return null
236
+ ownedRelease = () => {
237
+ interruptions.delete(ownedRelease)
238
+ release()
239
+ }
240
+ interruptions.add(ownedRelease)
241
+ return ownedRelease
242
+ },
243
+ credentials: scopeCredentials(credentialBackend, addonName),
189
244
  publish: (data: unknown) => {
190
245
  if (primaryChannel !== undefined) {
191
246
  bridge.broadcast({
@@ -229,7 +284,10 @@ export const bridgeAddonServices = async (
229
284
  }
230
285
 
231
286
  try {
232
- const result = globalService.onLoad?.(ctx)
287
+ const result = globalService.onLoad?.(
288
+ ctx,
289
+ addonServiceConfigs?.get(addonName),
290
+ )
233
291
  if (result instanceof Promise) {
234
292
  result.catch((err) => {
235
293
  logger.error({ addonName, err }, `addon onLoad failed`)
@@ -278,6 +336,7 @@ export const bridgeAddonServices = async (
278
336
  buttonAbort: AbortController
279
337
  buttonService: AddonButtonService
280
338
  wrappedCtx: AddonButtonServiceContext<unknown>
339
+ activate: () => void
281
340
  }>
282
341
  >()
283
342
  const mountedButtonSignatures = new Map<string, string>()
@@ -381,18 +440,40 @@ export const bridgeAddonServices = async (
381
440
  store,
382
441
  }
383
442
 
384
- const buttonAbort = new AbortController()
443
+ let buttonAbort = new AbortController()
385
444
  abortController.signal.addEventListener("abort", () =>
386
445
  buttonAbort.abort(),
387
446
  )
388
447
 
389
- const wrappedCtx = {
448
+ let wrappedCtx = {
390
449
  ...buttonCtx,
391
450
  signal: buttonAbort.signal,
392
451
  }
393
452
 
453
+ const entry = {
454
+ handlerId,
455
+ buttonAbort,
456
+ buttonService,
457
+ wrappedCtx,
458
+ activate: () => {
459
+ if (!buttonAbort.signal.aborted || abortController.signal.aborted)
460
+ return
461
+ buttonAbort = new AbortController()
462
+ wrappedCtx = { ...buttonCtx, signal: buttonAbort.signal }
463
+ entry.buttonAbort = buttonAbort
464
+ entry.wrappedCtx = wrappedCtx
465
+ try {
466
+ buttonService.onMount?.(wrappedCtx)
467
+ } catch (err) {
468
+ logger.error(
469
+ { addonName, buttonType, err },
470
+ `addon onMount threw`,
471
+ )
472
+ }
473
+ },
474
+ }
394
475
  const existing = deckButtonCleanup.get(deck.id) ?? []
395
- existing.push({ handlerId, buttonAbort, buttonService, wrappedCtx })
476
+ existing.push(entry)
396
477
  deckButtonCleanup.set(deck.id, existing)
397
478
 
398
479
  try {
@@ -509,6 +590,7 @@ export const bridgeAddonServices = async (
509
590
  const tracked = deckButtonCleanup.get(deckId)
510
591
  if (tracked === undefined) return
511
592
  for (const { buttonAbort, buttonService, wrappedCtx } of tracked) {
593
+ if (buttonAbort.signal.aborted) continue
512
594
  try {
513
595
  buttonService.onUnmount?.(wrappedCtx)
514
596
  } catch (err) {
@@ -519,18 +601,33 @@ export const bridgeAddonServices = async (
519
601
  },
520
602
  )
521
603
  trackedCleanup.push(unsubscribeDeckInactive)
604
+ trackedCleanup.push(
605
+ pubSub.subscribe("runtime:activeDeck", (payload: unknown) => {
606
+ if (
607
+ typeof payload !== "object" ||
608
+ payload === null ||
609
+ !("deckId" in payload)
610
+ )
611
+ return
612
+ for (const entry of deckButtonCleanup.get(String(payload.deckId)) ?? []) {
613
+ entry.activate()
614
+ }
615
+ }),
616
+ )
522
617
 
523
618
  abortController.signal.addEventListener("abort", () => {
524
619
  for (const [addonName, globalService] of addonGlobalServices) {
525
620
  try {
526
621
  const ctx: AddonServiceContext = {
622
+ getDataDirectory: addonDataDirectories.get(addonName),
623
+ credentials: scopeCredentials(credentialBackend, addonName),
527
624
  publish: () => {},
528
625
  poll: async () => {},
529
626
  signal: abortController.signal,
530
627
  executor,
531
628
  notify: methods.notify,
532
629
  }
533
- globalService.onUnload?.(ctx)
630
+ globalService.onUnload?.(ctx, addonServiceConfigs?.get(addonName))
534
631
  } catch (err) {
535
632
  logger.error({ addonName, err }, `addon onUnload failed`)
536
633
  }
@@ -546,13 +643,15 @@ export const bridgeAddonServices = async (
546
643
  for (const [addonName, globalService] of addonGlobalServices) {
547
644
  try {
548
645
  const ctx: AddonServiceContext = {
646
+ getDataDirectory: addonDataDirectories.get(addonName),
647
+ credentials: scopeCredentials(credentialBackend, addonName),
549
648
  publish: () => {},
550
649
  poll: async () => {},
551
650
  signal: abortController.signal,
552
651
  executor,
553
652
  notify: methods.notify,
554
653
  }
555
- globalService.onUnload?.(ctx)
654
+ globalService.onUnload?.(ctx, addonServiceConfigs?.get(addonName))
556
655
  } catch (err) {
557
656
  logger.error({ addonName, err }, `addon onUnload failed`)
558
657
  }
@@ -0,0 +1,94 @@
1
+ import type { AddonManifestV1 } from "@/addon/api"
2
+ import type { RuntimeButton, RuntimeDeck } from "./runtime"
3
+
4
+ const settingsId = "internal-settings:settings"
5
+
6
+ export const buildAddonSettingsDecks = (
7
+ decks: readonly RuntimeDeck[],
8
+ addons: readonly Pick<AddonManifestV1, "name" | "settings">[],
9
+ keyCount: number,
10
+ ): RuntimeDeck[] => {
11
+ const base = decks.find((deck) => deck.id === settingsId)
12
+ if (!base) return [...decks]
13
+ const compact = keyCount === 6
14
+ const entries = addons.filter((addon) => addon.settings !== undefined)
15
+ const start = compact ? 2 : 4
16
+ const available = keyCount - 1 - start
17
+ const paginated = entries.length > available
18
+ const pageSize = available - (paginated ? 1 : 0)
19
+ if (pageSize < 1) return [...decks]
20
+ const total = Math.max(1, Math.ceil(entries.length / pageSize))
21
+ const pageId = (page: number) =>
22
+ page === 0 ? settingsId : `${settingsId}-p${page + 1}`
23
+ const pages = Array.from({ length: total }, (_, page): RuntimeDeck => {
24
+ const buttons: RuntimeButton[] = compact
25
+ ? [
26
+ {
27
+ id: "app-info",
28
+ type: "internal-settings:compact-app-info",
29
+ position: 0,
30
+ config: { icon: "addon://internal-settings/logo72x72.png" },
31
+ },
32
+ {
33
+ id: "brightness",
34
+ type: "internal-settings:compact-brightness",
35
+ position: 1,
36
+ },
37
+ ]
38
+ : [
39
+ {
40
+ id: "app-info",
41
+ type: "internal-settings:app-info",
42
+ position: 0,
43
+ config: { icon: "addon://internal-settings/logo72x72.png" },
44
+ },
45
+ {
46
+ id: "brightness-down",
47
+ type: "internal-settings:brightness-down",
48
+ position: 1,
49
+ },
50
+ {
51
+ id: "brightness-up",
52
+ type: "internal-settings:brightness-up",
53
+ position: 2,
54
+ },
55
+ ]
56
+ for (const [index, addon] of entries
57
+ .slice(page * pageSize, (page + 1) * pageSize)
58
+ .entries()) {
59
+ const settings = addon.settings!
60
+ buttons.push({
61
+ id: `settings-${addon.name}`,
62
+ type: "core:change-deck",
63
+ position: start + index,
64
+ config: {
65
+ deck: settings.deck,
66
+ label: settings.label,
67
+ icon: settings.icon,
68
+ },
69
+ })
70
+ }
71
+ if (paginated)
72
+ buttons.push({
73
+ id: "page-nav",
74
+ type: "core:page-nav",
75
+ position: keyCount - 2,
76
+ config: {
77
+ currentPage: page + 1,
78
+ totalPages: total,
79
+ prevDeckId: pageId(Math.max(0, page - 1)),
80
+ nextDeckId: pageId(Math.min(total - 1, page + 1)),
81
+ },
82
+ })
83
+ return {
84
+ ...base,
85
+ id: pageId(page),
86
+ buttons,
87
+ sourceDeckId: settingsId,
88
+ projectionId: pageId(page),
89
+ pageIndex: page,
90
+ paginated,
91
+ }
92
+ })
93
+ return decks.flatMap((deck) => (deck.id === settingsId ? pages : [deck]))
94
+ }
@@ -214,6 +214,7 @@ export const buildDeckConfigMessage = (
214
214
  [deck.id]: {
215
215
  id: deck.id,
216
216
  name: deck.name ?? deck.id,
217
+ ...(deck.isModal === true ? { isModal: true } : {}),
217
218
  buttons: finalButtons,
218
219
  ...(deck.buttonColor !== undefined
219
220
  ? { buttonColor: deck.buttonColor }
@@ -3,21 +3,32 @@ import type { RuntimeDeck } from "./runtime"
3
3
  export const injectConfigUiButton = (
4
4
  decks: ReadonlyArray<RuntimeDeck>,
5
5
  configUiUrl: string,
6
+ keyCount = 15,
6
7
  ): RuntimeDeck[] =>
7
8
  decks.map((deck) =>
8
- deck.id !== "internal-settings:settings"
9
+ deck.id !== "internal-settings:settings" &&
10
+ !deck.id.startsWith("internal-settings:settings-p")
9
11
  ? deck
10
- : {
11
- ...deck,
12
- buttons: [
13
- ...deck.buttons,
14
- {
15
- id: "config-ui",
16
- type: "core:action",
17
- position: 3,
18
- config: { label: "Config UI", icon: "icon://settings" },
19
- actions: { tap: `url://${configUiUrl}` },
20
- },
21
- ],
22
- },
12
+ : keyCount === 6
13
+ ? {
14
+ ...deck,
15
+ buttons: deck.buttons.map((button) =>
16
+ button.type === "internal-settings:compact-app-info"
17
+ ? { ...button, actions: { tap: `url://${configUiUrl}` } }
18
+ : button,
19
+ ),
20
+ }
21
+ : {
22
+ ...deck,
23
+ buttons: [
24
+ ...deck.buttons,
25
+ {
26
+ id: "config-ui",
27
+ type: "core:action",
28
+ position: 3,
29
+ config: { label: "Config UI", icon: "icon://settings" },
30
+ actions: { tap: `url://${configUiUrl}` },
31
+ },
32
+ ],
33
+ },
23
34
  )
@@ -50,6 +50,7 @@ export interface RuntimeDeck {
50
50
  id: string
51
51
  name: string
52
52
  buttons: ReadonlyArray<RuntimeButton>
53
+ isModal?: boolean
53
54
  isMain?: boolean
54
55
  processNames?: ReadonlyArray<string>
55
56
  windowNames?: ReadonlyArray<string>
@@ -133,6 +134,14 @@ export interface Runtime {
133
134
  deckExists(id: string): boolean
134
135
  setDecks(decks: ReadonlyArray<RuntimeDeck>): void
135
136
  navigateToDeck(id: string, options?: { addToHistory?: boolean }): void
137
+ interruptDeck(
138
+ id: string,
139
+ options?: { onBack?: () => void | Promise<void> },
140
+ ): (() => void) | null
141
+ showModal(
142
+ id: string,
143
+ options?: { onOk?: () => void | Promise<void> },
144
+ ): (() => void) | null
136
145
  goBack(): void
137
146
  setOverlay(
138
147
  deckId: string | null,
@@ -212,6 +221,17 @@ export const createRuntime = (options: CreateRuntimeOptions): Runtime => {
212
221
  }
213
222
  let brightness = 50
214
223
  let lockActive = false
224
+ const modals: Array<{ deckId: string; onOk?: () => void | Promise<void> }> =
225
+ []
226
+ let deferredOverlay: {
227
+ deckId: string | null
228
+ source?: "autoShow" | "manual"
229
+ } | null = null
230
+ let interruption: {
231
+ deckId: string
232
+ onBack?: () => void | Promise<void>
233
+ backPending?: boolean
234
+ } | null = null
215
235
  let legacyActiveApp: Pick<ActiveAppProvider, "getActive" | "stop"> = {
216
236
  getActive: async () => null,
217
237
  stop: async () => undefined,
@@ -225,6 +245,19 @@ export const createRuntime = (options: CreateRuntimeOptions): Runtime => {
225
245
 
226
246
  const setDecks = (next: ReadonlyArray<RuntimeDeck>): void => {
227
247
  decks = next
248
+ const activeModal = modals[0]
249
+ for (let i = modals.length - 1; i >= 0; i--) {
250
+ if (deckById(modals[i]!.deckId) === undefined) modals.splice(i, 1)
251
+ }
252
+ if (!lockActive && activeModal && modals[0] !== activeModal) {
253
+ pubSub.publish("runtime:deck-inactive", { deckId: activeModal.deckId })
254
+ pubSub.publish("runtime:activeDeck", { deckId: getActiveDeckId() })
255
+ }
256
+ if (interruption !== null && deckById(interruption.deckId) === undefined) {
257
+ const previous = interruption.deckId
258
+ interruption = null
259
+ pubSub.publish("runtime:deck-inactive", { deckId: previous })
260
+ }
228
261
  // ponytail: rebuild a global button-id → ref map so bare-id lookups in
229
262
  // findButton are O(1) instead of scanning all decks in deck order. Set
230
263
  // first-wins (not last-wins) to preserve the legacy scan behavior.
@@ -276,11 +309,15 @@ export const createRuntime = (options: CreateRuntimeOptions): Runtime => {
276
309
  const id = getActiveDeckId()
277
310
  const deck = deckById(id)
278
311
  if (deck === undefined) throw new Error(`Active deck '${id}' not found`)
279
- return deck
312
+ return !lockActive && modals[0]?.deckId === id
313
+ ? { ...deck, isModal: true }
314
+ : deck
280
315
  }
281
316
 
282
317
  const getActiveDeckId = (): string => {
283
318
  if (lockActive) return "core:lock"
319
+ if (modals[0]) return modals[0].deckId
320
+ if (interruption !== null) return interruption.deckId
284
321
  // ponytail: while overlay mode is on, transientDeckId (used by page-nav)
285
322
  // must take precedence — otherwise paginated overlay pages are invisible
286
323
  // to the runtime, and dismissing overlay after paginating restores the
@@ -302,6 +339,53 @@ export const createRuntime = (options: CreateRuntimeOptions): Runtime => {
302
339
  navStack[navStack.length - 1] ??
303
340
  mainDeck.id
304
341
 
342
+ const showModal = (
343
+ id: string,
344
+ options?: { onOk?: () => void | Promise<void> },
345
+ ): (() => void) | null => {
346
+ if (!deckById(id)) return null
347
+ const previous = getActiveDeckId()
348
+ const entry = { deckId: id, onOk: options?.onOk }
349
+ modals.push(entry)
350
+ if (!lockActive && modals[0] === entry) {
351
+ pubSub.publish("runtime:deck-inactive", { deckId: previous })
352
+ pubSub.publish("runtime:activeDeck", { deckId: id })
353
+ }
354
+ return () => {
355
+ const index = modals.indexOf(entry)
356
+ if (index < 0) return
357
+ const wasActive = index === 0 && !lockActive
358
+ modals.splice(index, 1)
359
+ if (wasActive) {
360
+ pubSub.publish("runtime:deck-inactive", { deckId: id })
361
+ pubSub.publish("runtime:activeDeck", { deckId: getActiveDeckId() })
362
+ if (modals.length === 0 && deferredOverlay) {
363
+ const pending = deferredOverlay
364
+ deferredOverlay = null
365
+ setOverlay(pending.deckId, { source: pending.source })
366
+ }
367
+ }
368
+ }
369
+ }
370
+
371
+ const interruptDeck = (
372
+ id: string,
373
+ options?: { onBack?: () => void | Promise<void> },
374
+ ): (() => void) | null => {
375
+ if (lockActive || deckById(id) === undefined) return null
376
+ const previous = getActiveDeckId()
377
+ const current = { deckId: id, onBack: options?.onBack }
378
+ interruption = current
379
+ pubSub.publish("runtime:deck-inactive", { deckId: previous })
380
+ pubSub.publish("runtime:activeDeck", { deckId: id })
381
+ return () => {
382
+ if (interruption !== current) return
383
+ interruption = null
384
+ pubSub.publish("runtime:deck-inactive", { deckId: id })
385
+ pubSub.publish("runtime:activeDeck", { deckId: getActiveDeckId() })
386
+ }
387
+ }
388
+
305
389
  const enterLock = (): {
306
390
  activeDeckId: string
307
391
  overlayDeckId: string | null
@@ -312,6 +396,11 @@ export const createRuntime = (options: CreateRuntimeOptions): Runtime => {
312
396
  }
313
397
  if (lockActive) return snapshot
314
398
  lockActive = true
399
+ if (interruption !== null) {
400
+ const previous = interruption.deckId
401
+ interruption = null
402
+ pubSub.publish("runtime:deck-inactive", { deckId: previous })
403
+ }
315
404
  logger.info(snapshot, "runtime: lock active")
316
405
  pubSub.publish("runtime:lock-mode", {
317
406
  active: true,
@@ -326,6 +415,7 @@ export const createRuntime = (options: CreateRuntimeOptions): Runtime => {
326
415
  id: string,
327
416
  navOptions?: { addToHistory?: boolean },
328
417
  ): void => {
418
+ if (!lockActive && modals.length > 0) return
329
419
  if (id === getActiveDeckId()) return
330
420
  let resolvedId = id
331
421
  let target = deckById(id)
@@ -344,6 +434,15 @@ export const createRuntime = (options: CreateRuntimeOptions): Runtime => {
344
434
  logger.warn({ deckId: id }, "navigateToDeck: deck not found")
345
435
  return
346
436
  }
437
+ if (interruption !== null) {
438
+ const previous = interruption.deckId
439
+ interruption = null
440
+ pubSub.publish("runtime:deck-inactive", { deckId: previous })
441
+ if (getActiveDeckId() === resolvedId) {
442
+ pubSub.publish("runtime:activeDeck", { deckId: resolvedId })
443
+ return
444
+ }
445
+ }
347
446
  const previousActiveId = getActiveDeckId()
348
447
  if (overlayDeckId !== null) {
349
448
  // ponytail: while overlay mode is on, both change-deck (addToHistory:true)
@@ -371,12 +470,20 @@ export const createRuntime = (options: CreateRuntimeOptions): Runtime => {
371
470
  }
372
471
 
373
472
  const goBack = (): void => {
473
+ if (!lockActive && modals.length > 0) return
474
+ if (interruption !== null) {
475
+ const previous = interruption.deckId
476
+ interruption = null
477
+ pubSub.publish("runtime:deck-inactive", { deckId: previous })
478
+ pubSub.publish("runtime:activeDeck", { deckId: getActiveDeckId() })
479
+ return
480
+ }
374
481
  if (overlayDeckId !== null) {
375
482
  const stack = overlayNavStacks.get(overlayDeckId)
376
483
  if (stack !== undefined && stack.length > 1) {
377
- stack.pop()
484
+ const departed = stack.pop()!
378
485
  const prev = stack[stack.length - 1]!
379
- pubSub.publish("runtime:deck-inactive", { deckId: prev })
486
+ pubSub.publish("runtime:deck-inactive", { deckId: departed })
380
487
  pubSub.publish("runtime:activeDeck", { deckId: prev })
381
488
  } else {
382
489
  setOverlay(null)
@@ -416,10 +523,23 @@ export const createRuntime = (options: CreateRuntimeOptions): Runtime => {
416
523
  deckId: string | null,
417
524
  opts?: { source?: "autoShow" | "manual" },
418
525
  ): void => {
526
+ if (!lockActive && modals.length > 0) {
527
+ deferredOverlay = {
528
+ deckId,
529
+ ...(opts?.source ? { source: opts.source } : {}),
530
+ }
531
+ return
532
+ }
419
533
  if (deckId !== null && deckById(deckId) === undefined) {
420
534
  logger.warn({ deckId }, "setOverlay: deck not found")
421
535
  return
422
536
  }
537
+ if (interruption !== null && deckId === overlayDeckId) return
538
+ if (interruption !== null && deckId !== overlayDeckId) {
539
+ const previous = interruption.deckId
540
+ interruption = null
541
+ pubSub.publish("runtime:deck-inactive", { deckId: previous })
542
+ }
423
543
  if (deckId !== null && !overlayNavStacks.has(deckId)) {
424
544
  overlayNavStacks.set(deckId, [deckId])
425
545
  }
@@ -496,13 +616,53 @@ export const createRuntime = (options: CreateRuntimeOptions): Runtime => {
496
616
  }
497
617
 
498
618
  const handleSystemButton = (type: string, gesture: GestureKind): boolean => {
619
+ if (
620
+ (type === "core:back" || type === "core:modal-ok") &&
621
+ !lockActive &&
622
+ modals[0]
623
+ ) {
624
+ if (gesture === "tap" || gesture === "hold") {
625
+ const entry = modals.shift()!
626
+ pubSub.publish("runtime:deck-inactive", { deckId: entry.deckId })
627
+ pubSub.publish("runtime:activeDeck", { deckId: getActiveDeckId() })
628
+ if (modals.length === 0 && deferredOverlay) {
629
+ const pending = deferredOverlay
630
+ deferredOverlay = null
631
+ setOverlay(pending.deckId, { source: pending.source })
632
+ }
633
+ if (entry.onOk)
634
+ void Promise.resolve()
635
+ .then(entry.onOk)
636
+ .catch((err) => logger.error({ err }, "modal OK action failed"))
637
+ }
638
+ return true
639
+ }
499
640
  if (type === "core:back") {
500
641
  if (gesture === "tap") {
642
+ if (interruption?.onBack) {
643
+ const current = interruption
644
+ if (current.backPending) return true
645
+ current.backPending = true
646
+ void Promise.resolve()
647
+ .then(current.onBack)
648
+ .catch((err) =>
649
+ logger.error({ err }, "interruption back action failed"),
650
+ )
651
+ .finally(() => {
652
+ current.backPending = false
653
+ })
654
+ return true
655
+ }
501
656
  goBack()
502
657
  return true
503
658
  }
504
659
  if (gesture === "hold") {
505
660
  // ponytail: hold always goes to main, never toggles overlay
661
+ if (interruption !== null) {
662
+ const previous = interruption.deckId
663
+ interruption = null
664
+ pubSub.publish("runtime:deck-inactive", { deckId: previous })
665
+ }
506
666
  if (overlayDeckId !== null) setOverlay(null)
507
667
  navStack.length = 0
508
668
  navStack.push(mainDeck.id)
@@ -582,6 +742,8 @@ export const createRuntime = (options: CreateRuntimeOptions): Runtime => {
582
742
  return
583
743
  }
584
744
 
745
+ if (!lockActive && modals[0] && found.deckId !== modals[0].deckId) return
746
+
585
747
  try {
586
748
  if (handleSystemButton(found.button.type, gesture)) {
587
749
  return
@@ -772,6 +934,7 @@ export const createRuntime = (options: CreateRuntimeOptions): Runtime => {
772
934
  logger.warn({ buttonId }, "dispatchGesture: button not found")
773
935
  return
774
936
  }
937
+ if (!lockActive && modals[0] && found.deckId !== modals[0].deckId) return
775
938
  gestureListener?.(found.button.id, {
776
939
  gesture,
777
940
  at: Date.now(),
@@ -817,6 +980,13 @@ export const createRuntime = (options: CreateRuntimeOptions): Runtime => {
817
980
  reason: "session-unlocked",
818
981
  })
819
982
  pubSub.publish("runtime:invalidate", undefined)
983
+ if (modals[0])
984
+ pubSub.publish("runtime:activeDeck", { deckId: modals[0].deckId })
985
+ else if (deferredOverlay) {
986
+ const pending = deferredOverlay
987
+ deferredOverlay = null
988
+ setOverlay(pending.deckId, { source: pending.source })
989
+ }
820
990
  }
821
991
 
822
992
  const startLegacyPolicy = (): void => {
@@ -876,6 +1046,8 @@ export const createRuntime = (options: CreateRuntimeOptions): Runtime => {
876
1046
  deckById(id) !== undefined || deckById(`${id}-p1`) !== undefined,
877
1047
  setDecks,
878
1048
  navigateToDeck,
1049
+ interruptDeck,
1050
+ showModal,
879
1051
  goBack,
880
1052
  setOverlay,
881
1053
  getOverlay,
@@ -10,6 +10,7 @@ export interface RuntimeDeck {
10
10
  config?: unknown
11
11
  }>
12
12
  isMain?: boolean
13
+ isModal?: boolean
13
14
  processNames?: ReadonlyArray<string>
14
15
  windowNames?: ReadonlyArray<string>
15
16
  autoShow?: boolean
@@ -28,6 +29,7 @@ export const computeSystemButtonForSlotN1 = (
28
29
  state: RuntimeState,
29
30
  ): SystemButtonType | null => {
30
31
  if (state.lockActive === true) return null
32
+ if (deck.isModal) return "core:modal-ok"
31
33
  if (deck.isMain) return "core:settings-entry"
32
34
  // `core:back` gives the split surface distinct tap (back) and dbl-tap
33
35
  // (overlay toggle) actions, including while an overlay is active.