@cat-factory/app 0.237.0 → 0.237.1

package/app/stores/ui/navigation.ts

@@ -3,10 +3,14 @@ import type { LodLevel } from '~/types/domain'
 import { zoomToLod } from '~/composables/useSemanticZoom'
 
 /**
- * The board-navigation slice of the UI store: selection / focus, canvas zoom + the derived
- * level-of-detail, and the (retained) expanded-frame set. Hot paths (zoom/pan/select) live here,
- * isolated from the modal + result-view state, per refactoring candidate #4. Composed into
- * {@link useUiStore}; the returned refs/actions keep their names, so consumers are unchanged.
+ * The board-navigation slice of the UI store: selection / focus, and canvas zoom plus the derived
+ * level-of-detail. Hot paths (zoom/pan/select) live here, isolated from the modal + result-view
+ * state, per refactoring candidate #4. Composed into {@link useUiStore}; the returned refs/actions
+ * keep their names, so consumers are unchanged.
+ *
+ * There is deliberately no per-frame expanded/collapsed state: a service is always expanded to its
+ * task canvas, at every zoom level, so the board layout is fixed. The set that used to hold it
+ * outlived the last branch that read it and went with them.
  */
 export function createUiNavigation() {
   const selectedBlockId = ref<string | null>(null)
@@ -17,29 +21,6 @@ export function createUiNavigation() {
 
   const lod = computed<LodLevel>(() => zoomToLod(zoom.value))
 
-  /** Frames the user has manually expanded to reveal their tasks. */
-  const expandedFrames = ref<Set<string>>(new Set())
-
-  function toggleFrame(id: string) {
-    const next = new Set(expandedFrames.value)
-    if (next.has(id)) next.delete(id)
-    else next.add(id)
-    expandedFrames.value = next
-  }
-
-  function expandFrame(id: string) {
-    if (expandedFrames.value.has(id)) return
-    expandedFrames.value = new Set(expandedFrames.value).add(id)
-  }
-
-  /** Services are always expanded to their task canvas, at every zoom level, so the
-   * board layout is fixed: panning never changes it and zooming has no expand/collapse
-   * transition to snap on. (`expandedFrames`/`toggleFrame` are retained for callers but
-   * no longer gate rendering.) */
-  function isFrameExpanded(_id: string) {
-    return true
-  }
-
   function select(id: string | null) {
     selectedBlockId.value = id
   }
@@ -53,10 +34,6 @@ export function createUiNavigation() {
     focusBlockId,
     zoom,
     lod,
-    expandedFrames,
-    toggleFrame,
-    expandFrame,
-    isFrameExpanded,
     select,
     focus,
   }

package/app/utils/containerTargets.ts

@@ -0,0 +1,71 @@
+/**
+ * Where a board-authoring surface creates: the containers a new task may land in, and how that
+ * answer follows a live board.
+ *
+ * Pure so the reconcile below can be pinned by a unit test. `<TaskImportModal>` and
+ * `<BugHuntModal>` ask the same two-part question (a source to read, a container to land in) and
+ * are opened from the same frame-header buttons, so both read this through
+ * {@link useContainerTargets} rather than each carrying its own copy.
+ */
+import type { Block } from '~/types/domain'
+
+/** A container offered as a select item. */
+export interface ContainerTarget {
+  label: string
+  value: string
+}
+
+/** Only a service frame or one of its modules can hold a task. */
+export function isTaskContainer(block: Block | undefined): block is Block {
+  return !!block && (block.level === 'frame' || block.level === 'module')
+}
+
+/**
+ * The containers on offer, given the frame the surface was opened from (if any).
+ *
+ * Opened from a service frame the answer is SCOPED to that frame: the frame itself plus its
+ * modules, each labelled by its own title because the frame is already named on the surface. The
+ * frame settles WHICH SERVICE the work belongs to, which is the part a header button can answer;
+ * it does not settle frame-or-which-module, so a frame that has modules still owes the user a
+ * choice. Opened standalone there is no frame behind it, so every container on the board is a
+ * candidate and a module carries its parent's title to keep the choice unambiguous.
+ *
+ * `pinned` is resolved through the board by the caller rather than trusted as an id, so a frame
+ * deleted while the surface sat open widens back to the whole board instead of scoping to
+ * something nothing can be created in.
+ */
+export function containerTargets(
+  blocks: readonly Block[],
+  pinned: Block | undefined,
+): ContainerTarget[] {
+  if (pinned) {
+    // Modules cannot nest, so a pinned module is already the only answer.
+    if (pinned.level === 'module') return [{ label: pinned.title, value: pinned.id }]
+    const modules = blocks.filter((b) => b.level === 'module' && b.parentId === pinned.id)
+    return [pinned, ...modules].map((b) => ({ label: b.title, value: b.id }))
+  }
+  const byId = new Map(blocks.map((b) => [b.id, b]))
+  return blocks.filter(isTaskContainer).map((b) => ({
+    label:
+      b.level === 'module' ? `${byId.get(b.parentId ?? '')?.title ?? '?'} › ${b.title}` : b.title,
+    value: b.id,
+  }))
+}
+
+/**
+ * The container a surface should hold as the board changes underneath it: the current selection
+ * while it is still on offer, else the first one that is.
+ *
+ * Needed because "where does this land" is answered once, when the surface opens, and the board is
+ * live: the frame it was opened from can be deleted, or a module added to it, while it sits there.
+ * A selection left pointing at a deleted block is the worst of the three states, because nothing
+ * looks wrong: the picker renders with nothing selected while the issue search under it is still
+ * scoped to the block that is gone, and the create lands on an id the board no longer has.
+ */
+export function reconcileContainer(
+  targets: readonly ContainerTarget[],
+  selected: string | undefined,
+): string | undefined {
+  if (selected && targets.some((t) => t.value === selected)) return selected
+  return targets[0]?.value
+}

package/app/utils/sourcePicker.spec.ts

@@ -0,0 +1,258 @@
+import { describe, it, expect, vi } from 'vitest'
+import {
+  buildConnectionSourceChoices,
+  buildSourceChoices,
+  connectableSources,
+  menuIsPickable,
+  reconcileSource,
+  sourceMenuItems,
+} from './sourcePicker'
+import type { TaskSourceState } from '~/types/domain'
+
+/**
+ * The pure source-selection behind `<ContextIssuePicker>`, `<BugHuntModal>` and
+ * `<ContextDocumentPicker>`. Pins what the always-visible selector promises: the source in use is
+ * named even when it is the only one, a source the workspace hasn't got yet is offered as something
+ * to ADD (worded for its actual state), a menu with nothing to decide is not dressed as a control,
+ * and the selection stays valid as the offered set changes underneath it.
+ */
+const state = (source: string, { available = true, enabled = true } = {}): TaskSourceState =>
+  ({
+    source,
+    label: source.toUpperCase(),
+    icon: `i-lucide-${source}`,
+    available,
+    enabled,
+    credentialFields: [],
+    refLabel: '',
+    refPlaceholder: '',
+  }) as unknown as TaskSourceState
+
+describe('buildSourceChoices', () => {
+  it('lists a single offered tracker, marked active (the selector is never hidden)', () => {
+    const groups = buildSourceChoices([state('github')], 'github')
+    expect(groups).toEqual([
+      [
+        {
+          action: 'select',
+          source: 'github',
+          label: 'GITHUB',
+          icon: 'i-lucide-github',
+          active: true,
+        },
+      ],
+    ])
+  })
+
+  it('marks only the selected tracker active', () => {
+    const [offered] = buildSourceChoices([state('github'), state('jira')], 'jira')
+    expect(offered!.map((c) => [c.source, 'active' in c && c.active])).toEqual([
+      ['github', false],
+      ['jira', true],
+    ])
+  })
+
+  it('offers an unavailable tracker as `connect` and an available-but-off one as `enable`', () => {
+    const [, addable] = buildSourceChoices(
+      [state('github'), state('jira', { available: false }), state('linear', { enabled: false })],
+      'github',
+    )
+    expect(addable).toEqual([
+      { action: 'connect', source: 'jira', label: 'JIRA', icon: 'i-lucide-jira' },
+      { action: 'enable', source: 'linear', label: 'LINEAR', icon: 'i-lucide-linear' },
+    ])
+  })
+
+  // What a surface's "nothing connected yet" state renders its add buttons from: it flattens
+  // the groups, so every choice there has to be addable. A `select` leaking through would
+  // offer to connect a tracker the workspace already has.
+  it('yields only addable choices when the workspace offers no tracker', () => {
+    const choices = buildSourceChoices(
+      [state('jira', { available: false }), state('linear', { enabled: false })],
+      undefined,
+    ).flat()
+    expect(choices.map((c) => c.action)).toEqual(['connect', 'enable'])
+  })
+
+  it('drops empty groups so the menu renders no stray separator', () => {
+    expect(buildSourceChoices([state('github')], 'github')).toHaveLength(1)
+    expect(buildSourceChoices([state('jira', { available: false })], undefined)).toHaveLength(1)
+    expect(buildSourceChoices([], undefined)).toEqual([])
+  })
+})
+
+describe('connectableSources', () => {
+  const sources = [
+    { source: 'github', label: 'GitHub', icon: 'i-lucide-github' },
+    { source: 'confluence', label: 'Confluence', icon: 'i-lucide-file-text' },
+  ]
+  const isConnected = (source: string) => source === 'github'
+
+  it('offers only the sources the workspace has not connected', () => {
+    const rows = connectableSources(sources, { isConnected, canConnect: true, available: true })
+    expect(rows.map((s) => s.source)).toEqual(['confluence'])
+  })
+
+  // Connecting stores a workspace credential and stays admin-tier while attaching moved to the
+  // member tier, so a member's add tier is withheld rather than rendered into a 403.
+  it('withholds every source from a user who may not connect one', () => {
+    expect(
+      connectableSources(sources, { isConnected, canConnect: false, available: true }),
+    ).toEqual([])
+  })
+
+  // The term the three former copies of this rule disagreed about. An integration the deployment
+  // has not configured has nothing to connect TO, so it is not the same fact as "already connected"
+  // and must not rest on the store happening to clear its source list.
+  it('withholds every source when the integration is unavailable to the deployment', () => {
+    expect(
+      connectableSources(sources, { isConnected: () => false, canConnect: true, available: false }),
+    ).toEqual([])
+  })
+})
+
+describe('buildConnectionSourceChoices', () => {
+  const sources = [
+    { source: 'github', label: 'GitHub', icon: 'i-lucide-github' },
+    { source: 'confluence', label: 'Confluence', icon: 'i-lucide-file-text' },
+  ]
+  const isConnected = (source: string) => source === 'github'
+  const opts = { isConnected, canConnect: true, available: true, selected: 'github' }
+
+  it('offers the connected source and the rest as something to add', () => {
+    expect(buildConnectionSourceChoices(sources, opts)).toEqual([
+      [
+        {
+          action: 'select',
+          source: 'github',
+          label: 'GitHub',
+          icon: 'i-lucide-github',
+          active: true,
+        },
+      ],
+      [
+        {
+          action: 'connect',
+          source: 'confluence',
+          label: 'Confluence',
+          icon: 'i-lucide-file-text',
+        },
+      ],
+    ])
+  })
+
+  // No per-workspace toggle exists for these sources, so `enable` ("connected but switched off
+  // here") is a state they cannot be in. It is unrepresentable in the return TYPE, which is what
+  // stops a document surface wording an add entry as "Connect X" for a source already connected;
+  // this asserts the runtime half of that.
+  it('never words a document source as `enable`', () => {
+    const choices = buildConnectionSourceChoices(sources, {
+      ...opts,
+      isConnected: () => false,
+      selected: undefined,
+    })
+    expect(
+      choices
+        .flat()
+        .map((c) => c.action)
+        .every((action) => action === 'connect'),
+    ).toBe(true)
+  })
+
+  it('yields the connected tier alone for a member, with no add group', () => {
+    const choices = buildConnectionSourceChoices(sources, { ...opts, canConnect: false })
+    expect(choices).toHaveLength(1)
+    expect(choices[0]!.map((c) => c.source)).toEqual(['github'])
+  })
+})
+
+describe('menuIsPickable', () => {
+  // The papercut this exists for, and the one a member hits: a chevron opening a menu whose single
+  // entry re-selects what is already selected promises a choice that isn't there.
+  it('reports nothing to decide for a lone entry', () => {
+    expect(menuIsPickable([[{}]])).toBe(false)
+    expect(menuIsPickable([])).toBe(false)
+  })
+
+  it('counts across groups, so one source plus one to add IS a choice', () => {
+    expect(menuIsPickable([[{}], [{}]])).toBe(true)
+    expect(menuIsPickable([[{}, {}]])).toBe(true)
+  })
+})
+
+describe('sourceMenuItems', () => {
+  const onSelect = vi.fn()
+  const onAdd = vi.fn()
+
+  it('marks the selected source as CHECKED, not merely glyphed', () => {
+    const [offered] = sourceMenuItems(
+      buildSourceChoices([state('github'), state('jira')], 'jira'),
+      {
+        onSelect,
+        onAdd,
+        addLabel: { connect: (l) => `connect ${l}`, enable: (l) => `enable ${l}` },
+      },
+    )
+    expect(offered!.map((i) => [i.label, i.type, i.checked])).toEqual([
+      ['GITHUB', 'checkbox', false],
+      ['JIRA', 'checkbox', true],
+    ])
+  })
+
+  it('words each add entry for its own action and marks it with the plug icon', () => {
+    const [, addable] = sourceMenuItems(
+      buildSourceChoices(
+        [state('github'), state('jira', { available: false }), state('linear', { enabled: false })],
+        'github',
+      ),
+      {
+        onSelect,
+        onAdd,
+        addLabel: { connect: (l) => `connect ${l}`, enable: (l) => `enable ${l}` },
+      },
+    )
+    expect(addable!.map((i) => [i.label, i.icon])).toEqual([
+      ['connect JIRA', 'i-lucide-plug'],
+      ['enable LINEAR', 'i-lucide-plug'],
+    ])
+  })
+
+  // A connection-only menu owes ONE wording, and the type says so: passing `enable` here would not
+  // compile. That is the guard, and this pins the behaviour it guards.
+  it('takes only the `connect` wording for a connection-only menu', () => {
+    const items = sourceMenuItems(
+      buildConnectionSourceChoices(
+        [{ source: 'confluence', label: 'Confluence', icon: 'i-lucide-file-text' }],
+        { isConnected: () => false, canConnect: true, available: true, selected: undefined },
+      ),
+      { onSelect, onAdd, addLabel: { connect: (l) => `Connect ${l}` } },
+    )
+    expect(items.flat().map((i) => i.label)).toEqual(['Connect Confluence'])
+  })
+})
+
+describe('reconcileSource', () => {
+  it('selects the tracker the user just went off to connect, once it is offered', () => {
+    expect(reconcileSource(['github', 'jira'], 'github', 'jira')).toBe('jira')
+  })
+
+  it('keeps the current selection while the connect is still pending', () => {
+    expect(reconcileSource(['github'], 'github', 'jira')).toBe('github')
+  })
+
+  it('keeps a still-offered selection', () => {
+    expect(reconcileSource(['github', 'jira'], 'jira', null)).toBe('jira')
+  })
+
+  it('falls back to the first offered tracker when the selection stopped being offered', () => {
+    expect(reconcileSource(['github'], 'jira', null)).toBe('github')
+  })
+
+  it('selects the first offered tracker when nothing is selected yet', () => {
+    expect(reconcileSource(['github'], undefined, null)).toBe('github')
+  })
+
+  it('resolves to nothing when the workspace offers no tracker at all', () => {
+    expect(reconcileSource([], 'jira', 'jira')).toBeUndefined()
+  })
+})

package/app/utils/sourcePicker.ts

@@ -0,0 +1,251 @@
+/**
+ * Pure source-selection logic shared by every surface that picks an integration source: which
+ * one is selected, what its menu offers, and how that menu renders.
+ *
+ * The menu is deliberately two-tier (pick a source the workspace already has, or go and add one)
+ * because a source-picking surface is exactly where a user discovers the source they want is
+ * missing, and sending them off to the Integrations hub loses whatever they had in progress.
+ * Today `<ContextIssuePicker>` (attach a context issue) and `<BugHuntModal>` (scan a board for
+ * bugs) render it over TRACKERS, and `<ContextDocumentPicker>` (attach a context document) over
+ * DOCUMENT sources.
+ *
+ * The two integrations describe availability differently, so each gets its own CHOICE builder and
+ * they share one RENDERER. A tracker carries `available` plus a per-workspace `enabled` toggle, so
+ * it can be connected-but-off and its add entry has to say "enable" rather than "connect"; a
+ * document source is either connected or not, so `buildConnectionSourceChoices` cannot produce an
+ * `enable` choice at all. That is a fact about its RETURN TYPE rather than a convention, which is
+ * why these are two builders instead of one taking a flag: `sourceMenuItems` derives its wording
+ * map from what the choices can actually carry, so a document surface is not asked for wording it
+ * can never use, and a document source that one day GAINS a toggle fails the typecheck at every
+ * surface that renders it.
+ */
+import type { DropdownMenuItem } from '@nuxt/ui'
+
+/** What a menu needs to know about one configured source, whatever integration it belongs to. */
+export interface SourceAvailability<S extends string> {
+  source: S
+  label: string
+  icon: string
+  /** A credential / installation is in place, so the source can be read right now. */
+  available: boolean
+  /**
+   * The workspace offers it. A tracker carries a per-workspace toggle that can be off while its
+   * credential is in place; an integration with no such toggle passes `true`.
+   */
+  enabled: boolean
+}
+
+/** A source whose only state is "connected or not", with no per-workspace toggle behind it. */
+export interface ConnectableSource<S extends string> {
+  source: S
+  label: string
+  icon: string
+}
+
+/** The two ways a source that is not on offer yet can be added from a menu. */
+export type AddAction = 'connect' | 'enable'
+
+/** A source the surface can use right now. */
+interface SelectChoice<S extends string> {
+  action: 'select'
+  source: S
+  label: string
+  icon: string
+  active: boolean
+}
+
+/**
+ * A configured source that is not offered yet, so it can be added from here. `connect` has no
+ * credential/App behind it; `enable` is connected but toggled off for the workspace. Both open the
+ * same connect modal, which serves either case: only the wording differs, so the user isn't told
+ * to "connect" something already connected.
+ */
+interface AddChoice<S extends string, A extends AddAction> {
+  action: A
+  source: S
+  label: string
+  icon: string
+}
+
+/** One row of a source menu over an integration that has a per-workspace enable toggle. */
+export type SourceChoice<S extends string> = SelectChoice<S> | AddChoice<S, AddAction>
+
+/** One row of a source menu over an integration that is simply connected or not. */
+export type ConnectionSourceChoice<S extends string> = SelectChoice<S> | AddChoice<S, 'connect'>
+
+/**
+ * A source menu, as non-empty groups (the sources on offer, then the ones the user could add).
+ * Empty groups are dropped so the menu never renders a stray separator.
+ */
+export function buildSourceChoices<S extends string>(
+  sources: readonly SourceAvailability<S>[],
+  selected: S | undefined,
+): SourceChoice<S>[][] {
+  const offered: SourceChoice<S>[] = []
+  const addable: SourceChoice<S>[] = []
+  for (const s of sources) {
+    if (s.available && s.enabled) {
+      offered.push({
+        action: 'select',
+        source: s.source,
+        label: s.label,
+        icon: s.icon,
+        active: s.source === selected,
+      })
+    } else {
+      addable.push({
+        action: s.available ? 'enable' : 'connect',
+        source: s.source,
+        label: s.label,
+        icon: s.icon,
+      })
+    }
+  }
+  return [offered, addable].filter((group) => group.length > 0)
+}
+
+/**
+ * The sources the acting user could add right now: those the workspace has not connected, and
+ * NONE when the integration is unavailable to this deployment or the user may not connect one.
+ *
+ * The single answer to "which document sources could I connect", so the picker's add tier and the
+ * hosts' connect shortcuts cannot drift. Both terms matter and neither implies the other: an
+ * unavailable integration has nothing to connect TO, and connecting stores a workspace credential,
+ * which is admin-tier while ATTACHING what it holds is member-tier. Offering a member an add entry
+ * would open a connect modal, take a token and 403, so what they see is what they can use.
+ *
+ * `available` is the store's probe result, so `null` (not probed yet) offers nothing: we do not know
+ * that there is anything to connect to, and a menu entry is a claim that there is.
+ */
+export function connectableSources<S extends string, T extends { source: S }>(
+  sources: readonly T[],
+  opts: { isConnected: (source: S) => boolean; canConnect: boolean; available: boolean | null },
+): T[] {
+  if (opts.available !== true || !opts.canConnect) return []
+  return sources.filter((s) => !opts.isConnected(s.source))
+}
+
+/**
+ * A source menu for an integration that is either connected or not (document sources). Same two
+ * groups as {@link buildSourceChoices}, but the add tier can only ever be `connect`.
+ */
+export function buildConnectionSourceChoices<S extends string>(
+  sources: readonly ConnectableSource<S>[],
+  opts: {
+    isConnected: (source: S) => boolean
+    canConnect: boolean
+    available: boolean | null
+    selected: S | undefined
+  },
+): ConnectionSourceChoice<S>[][] {
+  const connected: ConnectionSourceChoice<S>[] = sources
+    .filter((s) => opts.isConnected(s.source))
+    .map((s) => ({
+      action: 'select',
+      source: s.source,
+      label: s.label,
+      icon: s.icon,
+      active: s.source === opts.selected,
+    }))
+  const addable: ConnectionSourceChoice<S>[] = connectableSources(sources, opts).map((s) => ({
+    action: 'connect',
+    source: s.source,
+    label: s.label,
+    icon: s.icon,
+  }))
+  return [connected, addable].filter((group) => group.length > 0)
+}
+
+/**
+ * Wording for each way a source can be ADDED, as an exhaustive `Record` over exactly the add
+ * actions the menu's own choices can carry. A tracker surface owes both spellings; a document
+ * surface owes only `connect`, and gains a typecheck failure rather than the wrong wording if that
+ * ever stops being true.
+ */
+export type AddSourceLabels<A extends AddAction> = Record<A, (label: string) => string>
+
+/**
+ * Render source choices as dropdown items. The ONE place the two-tier menu's presentation lives:
+ * the selected source is a CHECKED item rather than one carrying a decorative glyph, so a screen
+ * reader announces which source is in use instead of just naming it, and every add entry carries
+ * the plug icon that distinguishes "go and set this up" from "use this".
+ */
+export function sourceMenuItems<S extends string, A extends AddAction>(
+  groups: readonly (readonly (SelectChoice<S> | AddChoice<S, A>)[])[],
+  opts: {
+    onSelect: (source: S) => void
+    onAdd: (source: S) => void
+    addLabel: AddSourceLabels<A>
+  },
+): DropdownMenuItem[][] {
+  return groups.map((group) =>
+    group.map((choice) =>
+      isAddChoice(choice)
+        ? {
+            label: opts.addLabel[choice.action](choice.label),
+            icon: 'i-lucide-plug',
+            onSelect: () => opts.onAdd(choice.source),
+          }
+        : {
+            label: choice.label,
+            icon: choice.icon,
+            type: 'checkbox' as const,
+            checked: choice.active,
+            onSelect: () => opts.onSelect(choice.source),
+          },
+    ),
+  )
+}
+
+/**
+ * Whether a choice is an ADD entry. A hand-written predicate because the add member's `action` is
+ * the type parameter `A` rather than a literal, and TypeScript will not narrow a generic discriminant
+ * on its own: without this, reading `.active` off the select half fails to compile.
+ */
+function isAddChoice<S extends string, A extends AddAction>(
+  choice: SelectChoice<S> | AddChoice<S, A>,
+): choice is AddChoice<S, A> {
+  return choice.action !== 'select'
+}
+
+/**
+ * The ADD half of a menu's choices, flattened: what a surface renders as buttons when nothing is
+ * offered yet and there is no selection to make. Narrowed here rather than at each call site so the
+ * wording map stays exhaustive over what actually arrives, and so a `select` choice cannot leak into
+ * a row that offers to connect a source the workspace already has.
+ */
+export function addChoicesOf<S extends string, A extends AddAction>(
+  groups: readonly (readonly (SelectChoice<S> | AddChoice<S, A>)[])[],
+): AddChoice<S, A>[] {
+  return groups.flat().filter((choice) => isAddChoice(choice))
+}
+
+/**
+ * Whether a source menu has anything to decide. With a single entry the trigger can only re-pick
+ * what is already selected, so a surface names the source as a LABEL instead: a chevron opening a
+ * one-item menu promises a choice that isn't there. The state is reached most often by a member,
+ * whose add tier is withheld (see {@link connectableSources}), which is exactly the reader least
+ * able to tell a dead control from a broken one.
+ */
+export function menuIsPickable(groups: readonly (readonly unknown[])[]): boolean {
+  return groups.reduce((total, group) => total + group.length, 0) > 1
+}
+
+/**
+ * The source a surface should hold once the offered set changes: after a connect, a disconnect, or
+ * the per-workspace toggle flipping elsewhere.
+ *
+ * `awaiting` is the source the user just left to connect: the moment it becomes offered it wins, so
+ * they land back on the source they went to add rather than on whatever was selected before.
+ * Otherwise a still-offered selection is kept, and a selection that stopped being offered falls
+ * back to the first one (reading a source the workspace no longer offers only yields errors).
+ */
+export function reconcileSource<S extends string>(
+  offered: readonly S[],
+  selected: S | undefined,
+  awaiting: S | null,
+): S | undefined {
+  if (awaiting && offered.includes(awaiting)) return awaiting
+  if (selected && offered.includes(selected)) return selected
+  return offered[0]
+}