feat: workflow pins/favorites (BACKLOG Standing #5) (#50)

A plain ordered workflow-ID list (shared/store.ts's pinnedWorkflowIds,
persisted via the existing zustand `persist` localStorage tier, same
pattern as goal 0033's activeWorkTabKey) with a togglePinnedWorkflow
action. app/workflowFrecency.ts gains sortWorkflowsByPinnedAndFrecency,
partitioning pinned rows (in pin order) above the existing
frecency-sorted unpinned tail rather than a second ranking algorithm.

A subtle Primer PinIcon toggle lands on both the Quick Panel's and the
⌘K palette's workflow rows -- muted outline unpinned, accent-colored
once pinned. Along the way, found and fixed a real Primer interaction
bug: ActionList.Item's TrailingVisual wraps children in a VisualWrap
span with pointer-events: none (trailing visuals are decorative-only
by the library's own convention), which silently ate every click on
the toggle until pointer-events: auto was added back on the button
itself.

Vitest covers the pinned-above-frecency/pin-order/dropped-stale-id/
no-mutation cases; quick-panel.spec.ts gained a full
pin-sorts-above-frecency -> unpin-reverts -> persists-across-reload
e2e case.


Claude-Session: https://claude.ai/code/session_018pkViCNAuZp2vBv2K9AbUh

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: alicoding

frontend/e2e/quick-panel.spec.ts

@@ -291,3 +291,91 @@ test('a parked MCP write bumps the Quick Panel review badge live, no reload', as
   }
   await restoreMCPWriteDefaults(page)
 })
+
+// docs/goals/BACKLOG.md Standing #5 -- workflow pins/favorites.
+// workflowFrecency.test.ts already covers the pure
+// sortWorkflowsByPinnedAndFrecency function; this proves the live
+// wiring end to end: pinning via the panel row's own toggle overrides
+// frecency ranking, unpinning reverts to it, and the pin survives a
+// reload (the localStorage-tier persistence the schema calls for).
+test('pinning a workflow from the panel row sorts it above frecency, unpinning reverts, and the pin persists across reload', async ({ page }) => {
+  const pinnedLabel = 'ZzE2ePinTargetPinned'
+  const frequentLabel = 'ZzE2ePinTargetFrequent'
+  // frequentLabel created FIRST, pinnedLabel second -- so absent any
+  // pin, frequentLabel's own run count would already outrank
+  // pinnedLabel (same "real proof, not a coincidental pass" discipline
+  // as the frecency test above).
+  await createSimpleWorkflow(page, frequentLabel)
+  await createSimpleWorkflow(page, pinnedLabel)
+
+  await page.goto('about:blank')
+  await page.goto('/#/quickpanel')
+  const search = page.getByRole('combobox', { name: 'Quick Panel search' })
+  await expect(search).toBeFocused()
+
+  // Build up frequentLabel's frecency via the panel's own Enter-to-run
+  // path, same as the frecency test above.
+  for (let i = 0; i < 2; i++) {
+    await search.fill(frequentLabel)
+    await expect(page.getByRole('option', { name: frequentLabel })).toBeVisible()
+    await page.keyboard.press('Enter')
+    await expect(page.getByTestId('quick-panel-status')).toContainText(`Started "${frequentLabel}"`)
+    await search.fill('')
+  }
+
+  const orderedLabels = async () => {
+    await search.fill('ZzE2ePinTarget')
+    const texts = await page.getByRole('option').allTextContents()
+    return texts
+  }
+
+  // Before pinning: DBOS run history becomes queryable shortly after
+  // RunWorkflow returns, not necessarily synchronously -- retry the
+  // fresh-mount reload + order check rather than a fixed sleep, same
+  // as the frecency test.
+  await expect(async () => {
+    await page.goto('about:blank')
+    await page.goto('/#/quickpanel')
+    await expect(search).toBeFocused()
+    const texts = await orderedLabels()
+    const frequentIndex = texts.findIndex((t) => t.includes(frequentLabel))
+    const pinnedIndex = texts.findIndex((t) => t.includes(pinnedLabel))
+    expect(frequentIndex).toBeGreaterThanOrEqual(0)
+    expect(pinnedIndex).toBeGreaterThanOrEqual(0)
+    expect(frequentIndex).toBeLessThan(pinnedIndex)
+  }).toPass({ timeout: 15_000 })
+
+  // Pin the never-run workflow via its row's pin toggle -- it should
+  // now sort ABOVE the frequently-run one despite having zero runs.
+  await search.fill(pinnedLabel)
+  await expect(page.getByRole('option', { name: pinnedLabel })).toBeVisible()
+  await page.getByRole('button', { name: `Pin "${pinnedLabel}"` }).click()
+  await expect(page.getByRole('button', { name: `Unpin "${pinnedLabel}"` })).toBeVisible()
+
+  let texts = await orderedLabels()
+  let frequentIndex = texts.findIndex((t) => t.includes(frequentLabel))
+  let pinnedIndex = texts.findIndex((t) => t.includes(pinnedLabel))
+  expect(pinnedIndex).toBeLessThan(frequentIndex)
+
+  // Persists across reload: a fresh mount of the same window still
+  // shows the pin above frecency, with no re-pinning gesture.
+  await page.goto('about:blank')
+  await page.goto('/#/quickpanel')
+  await expect(page.getByRole('combobox', { name: 'Quick Panel search' })).toBeFocused()
+  texts = await orderedLabels()
+  frequentIndex = texts.findIndex((t) => t.includes(frequentLabel))
+  pinnedIndex = texts.findIndex((t) => t.includes(pinnedLabel))
+  expect(pinnedIndex).toBeLessThan(frequentIndex)
+  await expect(page.getByRole('button', { name: `Unpin "${pinnedLabel}"` })).toBeVisible()
+
+  // Unpinning reverts to frecency order.
+  await page.getByRole('button', { name: `Unpin "${pinnedLabel}"` }).click()
+  await expect(page.getByRole('button', { name: `Pin "${pinnedLabel}"` })).toBeVisible()
+  texts = await orderedLabels()
+  frequentIndex = texts.findIndex((t) => t.includes(frequentLabel))
+  pinnedIndex = texts.findIndex((t) => t.includes(pinnedLabel))
+  expect(frequentIndex).toBeLessThan(pinnedIndex)
+
+  await deleteWorkflow(page, pinnedLabel)
+  await deleteWorkflow(page, frequentLabel)
+})

frontend/src/app/CommandPalette.module.css

@@ -25,3 +25,18 @@
 .list {
   max-height: min(60vh, 480px);
 }
+
+/* Workflow pin toggle (docs/goals/BACKLOG.md Standing #5) -- same pair
+   (including the `pointer-events: auto` override of Primer's own
+   trailingVisual `VisualWrap` reset) as app/QuickPanel.module.css's
+   identical classes; see that file's own comment for the full
+   reasoning. */
+.pinToggle {
+  color: var(--fgColor-muted);
+  pointer-events: auto;
+}
+
+.pinnedIndicator {
+  color: var(--fgColor-accent);
+  pointer-events: auto;
+}

frontend/src/app/CommandPalette.tsx

@@ -1,9 +1,9 @@
 import { useEffect, useMemo, useRef, useState } from 'react'
 import type { ElementType, ReactNode } from 'react'
 import { useTranslation } from 'react-i18next'
-import { Dialog, Text } from '@primer/react'
+import { Dialog, IconButton, Text } from '@primer/react'
 import { FilteredActionList } from '@primer/react/experimental'
-import { CommandPaletteIcon, PencilIcon, PlayIcon, TabIcon, XIcon } from '@primer/octicons-react'
+import { CommandPaletteIcon, PencilIcon, PinIcon, PlayIcon, TabIcon, XIcon } from '@primer/octicons-react'
 import { ExecutionService, RunKind } from '../shared/bindings'
 import { COMMANDS } from '../shared/commands'
 import { generateSamplePayload } from '../shared/configSchema'
@@ -14,7 +14,7 @@ import { findRootNode } from '../composition/triggerRowInfo'
 import { clearScratch } from '../composition/canvasScratch'
 import { filterPaletteEntries } from './paletteFilter'
 import type { PaletteSearchable } from './paletteFilter'
-import { sortWorkflowsByFrecency } from './workflowFrecency'
+import { sortWorkflowsByPinnedAndFrecency } from './workflowFrecency'
 import { HotkeyHint } from './HotkeyHint'
 import styles from './CommandPalette.module.css'
 
@@ -120,6 +120,12 @@ export function CommandPalette() {
   const activateWorkTab = useAppStore((s) => s.activateWorkTab)
   const closeWorkTab = useAppStore((s) => s.closeWorkTab)
   const pushActivity = useAppStore((s) => s.pushActivity)
+  // Workflow pins/favorites (docs/goals/BACKLOG.md Standing #5) -- same
+  // store-owned ordered id list app/QuickPanel.tsx reads, shared across
+  // both surfaces since they run in the same main-window JS context
+  // (unlike the Quick Panel's separate Wails window).
+  const pinnedWorkflowIds = useAppStore((s) => s.pinnedWorkflowIds)
+  const togglePinnedWorkflow = useAppStore((s) => s.togglePinnedWorkflow)
   const [query, setQuery] = useState('')
   const [mostUsedRank, setMostUsedRank] = useState<Record<string, number>>({})
   const inputRef = useRef<HTMLInputElement>(null)
@@ -206,6 +212,7 @@ export function CommandPalette() {
   const workflowEntries = (wf: NonNullable<typeof workflows>[number]): PaletteEntry[] => {
     const root = findRootNode(wf.Nodes, wf.Edges)
     const kindLabel = root ? nodeTypes?.find((nt) => nt.ID === root.NodeTypeID)?.Label : undefined
+    const pinned = pinnedWorkflowIds.includes(wf.ID)
     return [
       {
         id: `run:${wf.ID}`,
@@ -214,6 +221,24 @@ export function CommandPalette() {
         description: kindLabel ?? t('commandPalette.testRun'),
         searchText: `run ${wf.Label}`.toLowerCase(),
         leadingVisual: PlayIcon,
+        // A subtle pin toggle (docs/goals/BACKLOG.md Standing #5),
+        // same shape app/QuickPanel.tsx's own workflow row carries --
+        // stopPropagation so the click doesn't also trigger the row's
+        // own onAction (which would run the workflow AND close the
+        // palette).
+        trailingVisual: (
+          <IconButton
+            icon={PinIcon}
+            aria-label={pinned ? t('commandPalette.unpinWorkflow', { label: wf.Label }) : t('commandPalette.pinWorkflow', { label: wf.Label })}
+            size="small"
+            variant="invisible"
+            className={pinned ? styles.pinnedIndicator : styles.pinToggle}
+            onClick={(e) => {
+              e.stopPropagation()
+              togglePinnedWorkflow(wf.ID)
+            }}
+          />
+        ),
         run: () => runWorkflowTest(wf.ID, wf.Label),
       },
       {
@@ -266,16 +291,16 @@ export function CommandPalette() {
   const allEntries = useMemo<PaletteEntry[]>(() => {
     if (restState) {
       const navCommands = COMMANDS.filter((c) => isNavCommandId(c.id)).map(commandEntry)
-      const topWorkflows = sortWorkflowsByFrecency(workflows ?? [], mostUsedRank).slice(0, REST_STATE_WORKFLOW_LIMIT)
+      const topWorkflows = sortWorkflowsByPinnedAndFrecency(workflows ?? [], mostUsedRank, pinnedWorkflowIds).slice(0, REST_STATE_WORKFLOW_LIMIT)
       return [...navCommands, ...topWorkflows.flatMap(workflowEntries), ...workTabs.flatMap(tabEntries)]
     }
     return [
       ...COMMANDS.map(commandEntry),
-      ...(workflows ?? []).flatMap(workflowEntries),
+      ...sortWorkflowsByPinnedAndFrecency(workflows ?? [], mostUsedRank, pinnedWorkflowIds).flatMap(workflowEntries),
       ...workTabs.flatMap(tabEntries),
     ]
-    // eslint-disable-next-line react-hooks/exhaustive-deps -- commandEntry/workflowEntries/tabEntries close over workflows/nodeTypes/requests/workTabs/mostUsedRank/t, already listed
-  }, [restState, workflows, nodeTypes, requests, workTabs, mostUsedRank, t])
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- commandEntry/workflowEntries/tabEntries close over workflows/nodeTypes/requests/workTabs/mostUsedRank/pinnedWorkflowIds/togglePinnedWorkflow/t, already listed
+  }, [restState, workflows, nodeTypes, requests, workTabs, mostUsedRank, pinnedWorkflowIds, t])
 
   const filtered = restState ? allEntries : filterPaletteEntries(allEntries, query)
 

frontend/src/app/QuickPanel.module.css

@@ -19,3 +19,26 @@
   color: var(--fgColor-muted);
   border-top: 1px solid var(--borderColor-default);
 }
+
+/* Workflow pin toggle (docs/goals/BACKLOG.md Standing #5): subtle
+   muted outline when unpinned, accent-colored "filled" indicator once
+   pinned -- both states are the same IconButton (PinIcon), just
+   recolored via currentColor, matching CommandPalette.module.css's
+   identical pair below. `pointer-events: auto` re-enables clicking:
+   Primer's own ActionList.Item wraps every trailingVisual in a
+   `VisualWrap` span with `pointer-events: none` (its trailing visuals
+   are decorative by convention, not interactive) -- confirmed directly
+   against the installed @primer/react's compiled ActionList.module.css,
+   not assumed. A `none` ancestor still lets a descendant re-enable
+   itself via `auto`, which is exactly what turns this row's pin toggle
+   back into a real click target without fighting the library's own
+   pointer-events reset. */
+.pinToggle {
+  color: var(--fgColor-muted);
+  pointer-events: auto;
+}
+
+.pinnedIndicator {
+  color: var(--fgColor-accent);
+  pointer-events: auto;
+}

frontend/src/app/QuickPanel.tsx

@@ -2,9 +2,9 @@ import { useEffect, useMemo, useRef, useState } from 'react'
 import type { ElementType, ReactNode } from 'react'
 import { useTranslation } from 'react-i18next'
 import { Events } from '@wailsio/runtime'
-import { CounterLabel, Text } from '@primer/react'
+import { CounterLabel, IconButton, Text } from '@primer/react'
 import { FilteredActionList } from '@primer/react/experimental'
-import { CopyIcon, GearIcon, HomeIcon, PlayIcon } from '@primer/octicons-react'
+import { CopyIcon, GearIcon, HomeIcon, PinIcon, PlayIcon } from '@primer/octicons-react'
 import { CompositionService, ExecutionService, RunKind, SettingsService } from '../shared/bindings'
 import type { ClipboardApplyPreview } from '../shared/bindings'
 import { generateSamplePayload } from '../shared/configSchema'
@@ -14,7 +14,7 @@ import { ENTITY_ICON } from '../shared/entityIcons'
 import { CAPABILITY_ICON } from './navIcon'
 import { filterPaletteEntries } from './paletteFilter'
 import type { PaletteSearchable } from './paletteFilter'
-import { sortWorkflowsByFrecency } from './workflowFrecency'
+import { sortWorkflowsByPinnedAndFrecency } from './workflowFrecency'
 import { HotkeyHint } from './HotkeyHint'
 import { QuickPanelClipboardApply } from './QuickPanelClipboardApply'
 import styles from './QuickPanel.module.css'
@@ -85,6 +85,11 @@ export function QuickPanel() {
   const requests = useAppStore((s) => s.requests)
   const lists = useConfigureEntityStore((s) => s.lists)
   const mcpServers = useConfigureEntityStore((s) => s.mcpServers)
+  // Workflow pins/favorites (docs/goals/BACKLOG.md Standing #5): a
+  // plain ordered workflow-ID list, store-owned/localStorage-tier --
+  // see shared/store.ts's own declaration comment for the schema.
+  const pinnedWorkflowIds = useAppStore((s) => s.pinnedWorkflowIds)
+  const togglePinnedWorkflow = useAppStore((s) => s.togglePinnedWorkflow)
   const [query, setQuery] = useState('')
   const [status, setStatus] = useState<string | null>(null)
   // Frecency ranking (goal 0015's remainder item 1): workflowID ->
@@ -301,16 +306,34 @@ export function QuickPanel() {
 
   const allEntries = useMemo<PanelEntry[]>(() => {
     const entries: PanelEntry[] = []
-    // Frecency-sorted (goal 0015's remainder item 1) -- frequency-only,
-    // see mostUsedRank's own declaration comment.
-    for (const wf of sortWorkflowsByFrecency(workflows ?? [], mostUsedRank)) {
+    // Pinned-then-frecency-sorted (docs/goals/BACKLOG.md Standing #5 +
+    // goal 0015's remainder item 1) -- frequency-only among the
+    // unpinned tail, see mostUsedRank's own declaration comment.
+    for (const wf of sortWorkflowsByPinnedAndFrecency(workflows ?? [], mostUsedRank, pinnedWorkflowIds)) {
+      const pinned = pinnedWorkflowIds.includes(wf.ID)
       entries.push({
         id: `run:${wf.ID}`,
         groupId: 'workflows',
         text: wf.Label,
         description: t('quickPanel.entries.enterToRun'),
         searchText: wf.Label.toLowerCase(),
         leadingVisual: PlayIcon,
+        // A subtle pin toggle (stopPropagation so the click doesn't
+        // also fire the row's own onAction/run) -- pinned shows a
+        // filled/accent-colored indicator, unpinned a muted outline.
+        trailingVisual: (
+          <IconButton
+            icon={PinIcon}
+            aria-label={pinned ? t('quickPanel.entries.unpinWorkflow', { label: wf.Label }) : t('quickPanel.entries.pinWorkflow', { label: wf.Label })}
+            size="small"
+            variant="invisible"
+            className={pinned ? styles.pinnedIndicator : styles.pinToggle}
+            onClick={(e) => {
+              e.stopPropagation()
+              togglePinnedWorkflow(wf.ID)
+            }}
+          />
+        ),
         run: () => runWorkflow(wf.ID, wf.Label),
       })
     }
@@ -410,8 +433,8 @@ export function QuickPanel() {
       run: applyFromClipboard,
     })
     return entries
-    // eslint-disable-next-line react-hooks/exhaustive-deps -- runWorkflow/jumpToConfigure/openMain/applyFromClipboard close over state already listed or are stable
-  }, [workflows, mostUsedRank, requests, lists, mcpServers, reviewPendingCount])
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- runWorkflow/jumpToConfigure/openMain/applyFromClipboard/togglePinnedWorkflow close over state already listed or are stable
+  }, [workflows, mostUsedRank, pinnedWorkflowIds, requests, lists, mcpServers, reviewPendingCount])
 
   const filtered = filterPaletteEntries(allEntries, query)
 

frontend/src/app/workflowFrecency.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest'
-import { sortWorkflowsByFrecency } from './workflowFrecency'
+import { sortWorkflowsByFrecency, sortWorkflowsByPinnedAndFrecency } from './workflowFrecency'
 import type { Workflow } from '../../bindings/github.com/alicoding/mill/internal/domain/composition/models'
 
 // Minimal-but-valid Workflow fixture -- every field the interface
@@ -53,3 +53,51 @@ describe('sortWorkflowsByFrecency', () => {
     expect(list.map((w) => w.ID)).toEqual(['wf-1', 'wf-2'])
   })
 })
+
+describe('sortWorkflowsByPinnedAndFrecency', () => {
+  it('sorts a pinned workflow above a higher-frecency unpinned one', () => {
+    const pinned = makeWorkflow('wf-pinned')
+    const frequentlyRun = makeWorkflow('wf-frequently-run')
+    const sorted = sortWorkflowsByPinnedAndFrecency(
+      [frequentlyRun, pinned],
+      { 'wf-frequently-run': 99 },
+      ['wf-pinned'],
+    )
+    expect(sorted.map((w) => w.ID)).toEqual(['wf-pinned', 'wf-frequently-run'])
+  })
+
+  it('orders multiple pinned workflows by pin order (pin recency), not frecency', () => {
+    const a = makeWorkflow('wf-a')
+    const b = makeWorkflow('wf-b')
+    // b was run more often, but a was pinned first -- pin order wins
+    // among pinned rows.
+    const sorted = sortWorkflowsByPinnedAndFrecency([b, a], { 'wf-b': 50, 'wf-a': 1 }, ['wf-a', 'wf-b'])
+    expect(sorted.map((w) => w.ID)).toEqual(['wf-a', 'wf-b'])
+  })
+
+  it('falls back to frecency ordering for the unpinned tail, stable for ties', () => {
+    const pinned = makeWorkflow('wf-pinned')
+    const high = makeWorkflow('wf-high')
+    const low = makeWorkflow('wf-low')
+    const zero1 = makeWorkflow('wf-zero-1')
+    const zero2 = makeWorkflow('wf-zero-2')
+    const sorted = sortWorkflowsByPinnedAndFrecency(
+      [zero1, low, zero2, high, pinned],
+      { high: 0, 'wf-high': 9, 'wf-low': 2 },
+      ['wf-pinned'],
+    )
+    expect(sorted.map((w) => w.ID)).toEqual(['wf-pinned', 'wf-high', 'wf-low', 'wf-zero-1', 'wf-zero-2'])
+  })
+
+  it('a pinned id with no matching workflow is silently dropped, not rendered as a gap', () => {
+    const a = makeWorkflow('wf-a')
+    const sorted = sortWorkflowsByPinnedAndFrecency([a], {}, ['wf-deleted', 'wf-a'])
+    expect(sorted.map((w) => w.ID)).toEqual(['wf-a'])
+  })
+
+  it('does not mutate the input array', () => {
+    const list = [makeWorkflow('wf-1'), makeWorkflow('wf-2')]
+    sortWorkflowsByPinnedAndFrecency(list, {}, ['wf-2'])
+    expect(list.map((w) => w.ID)).toEqual(['wf-1', 'wf-2'])
+  })
+})

frontend/src/app/workflowFrecency.ts

@@ -29,3 +29,26 @@ export function sortWorkflowsByFrecency(workflows: Workflow[], runCounts: Record
   // survives unchanged until real usage data exists to reorder it.
   return [...workflows].sort((a, b) => (runCounts[b.ID] ?? 0) - (runCounts[a.ID] ?? 0))
 }
+
+// Workflow pins/favorites (docs/goals/BACKLOG.md Standing #5, split
+// from goal 0015's remainder, schema LOCKED at prioritization): pinned
+// rows sort ABOVE every frecency-sorted unpinned row, in `pinnedIds`'s
+// own order (pin recency -- see shared/store.ts's togglePinnedWorkflow).
+// A plain partition-then-concat over the existing frecency sort rather
+// than a new comparator -- reuses sortWorkflowsByFrecency for the
+// unpinned tail instead of re-deriving frecency ordering here too.
+export function sortWorkflowsByPinnedAndFrecency(
+  workflows: Workflow[],
+  runCounts: Record<string, number>,
+  pinnedIds: string[],
+): Workflow[] {
+  const pinnedSet = new Set(pinnedIds)
+  const pinned = pinnedIds
+    .map((id) => workflows.find((wf) => wf.ID === id))
+    .filter((wf): wf is Workflow => wf !== undefined)
+  const unpinned = sortWorkflowsByFrecency(
+    workflows.filter((wf) => !pinnedSet.has(wf.ID)),
+    runCounts,
+  )
+  return [...pinned, ...unpinned]
+}