feat(web): scratchlist v1.1 — composer-toggle drawer + reusable FUE primitive

[heavygee]

Summary

After dogfooding the per-session scratchlist (#777, merged via #772) for ~24h, the always-visible amber band proved too heavy for what's a 20% feature in a typical session. This PR dials it back to a composer-toggle that opens an on-demand drawer, paired with a small reusable FUE (First-User Experience) primitive so existing operators discover it without a giant always-on UI block.

Closes #797.

UX changes

• New notepad icon in the composer toolbar (next to schedule-send) toggles "scratchlist mode".
• Drawer renders only while mode is on (otherwise: chat-only, no vertical real estate consumed).
• While in mode, the composer's send button repaints amber and reads "Send to scratchlist" — submit routes adds into the scratchlist instead of the chat. Click the icon again to leave.
• Small entry-counter badge appears on the toggle when entries exist; empty-state shows just the icon (no zero-state guilt UI).
• Promote-to-composer / promote-to-queue / delete / reorder are unchanged.

Reusable FUE primitive

This is the structural payoff: a generic First-User-Experience helper so any new feature can advertise itself without a heavyweight tour.

• web/src/lib/use-fue.ts: useFue(featureId) returns { status, engage, dismiss } with state machine unseen → engaging → acknowledged. Persisted to localStorage under hapi.fue.v1.<featureId> (namespaced so it can never collide with any future upstream onboarding system).
• web/src/components/Fue.tsx: <FueDot> (small pulsing badge for the affordance) and <FueCallout> (portal-rendered popover with title/body + "Got it" button). No auto-timeout — reading speed varies and silent disappearance undercuts user trust.
• AGENTS.md adds a new "Adding new web features — consider an FUE" section so future contributors find the primitive.

Refactors

• ScratchlistPanel.tsx: split rendering into <ScratchlistInventory> (presentational list) and <ScratchlistDrawer> (composer-controlled drawer with hint copy). Original <ScratchlistPanel> is kept exported for the existing fixture-based tests.
• SessionChat.tsx: scratchlist state lifted into a new useScratchlist hook so the composer-toolbar counter and the drawer share one source of truth. onSend wrapped to route through scratchlist.add when mode is on.
• HappyComposer / ComposerButtons: thread through scratchlistMode, scratchlistCount, onScratchlistToggle props.

Tests

Suite	Tests	New / Existing
useFue (hook)	9	New
computeFueCalloutPlacement	5	New
scratchlist lib	21	Existing — green
ScratchlistPanel component	14	Existing — green
Full web suite	750	All green

bun typecheck clean across cli/web/hub.

Test plan

• Hard-refresh on a fresh browser session: pulsing amber dot appears on the notepad icon.
• Hover the icon: native tooltip reads "Scratchlist — park notes & drafts (click to open)".
• Click the icon: drawer opens above composer, FUE callout pops above the icon with "Got it" button. Composer send button is amber and reads "Send to scratchlist".
• Type something + Enter: text added to scratchlist, composer cleared, mode still on.
• Click "Got it" on the callout: callout dismisses, FUE marker stays as a static (non-pulsing) state — wait, no, dot vanishes, replaced by entry counter (number badge) since count > 0.
• Hard-refresh: dot is gone permanently (acknowledged in localStorage). Entry counter still shows count.
• Click the icon again (while in mode): drawer hides, composer back to normal chat send.
• Reset and re-test: localStorage.removeItem('hapi.fue.v1.scratchlist-toggle') then refresh — pulsing dot is back.
• Existing v1 behavior (promote-to-composer, promote-to-queue, delete with confirmation, reorder) still works inside the new drawer.

Notes

• The original <ScratchlistPanel> symbol is intentionally kept exported. The existing scratchlist-fixture.html Playwright e2e tests mount it directly; deleting it would have meant rewriting that fixture in this PR. A future PR can drop the legacy symbol once we've decided whether to port the e2e tests to the drawer.
• localStorage is still the only persistence layer (no hub-side scratchlist sync). v2 territory.

[github-actions]

Findings

• [Major] Prevent session switches from overwriting scratchlists — useScratchlist persists current entries whenever sessionId changes. On A -> B navigation, React first commits with B's id and A's entries; after paint, this persist effect can write A's entries to hapi.scratchlist.v1.B before the rehydrate effect loads B. The previous keyed panel existed specifically to avoid this race. Evidence web/src/lib/use-scratchlist.ts:27.
  Suggested fix:

  const [{ sessionId: loadedSessionId, entries }, setScratchlist] = useState(() => ({
      sessionId,
      entries: readScratchlist(sessionId),
  }))
  
  useEffect(() => {
      setScratchlist({ sessionId, entries: readScratchlist(sessionId) })
  }, [sessionId])
  
  useEffect(() => {
      persistScratchlist(loadedSessionId, entries)
  }, [loadedSessionId, entries])

Questions

• None.

Summary

• Review mode: initial
• One data-loss regression found in the new lifted scratchlist hook. Residual risk: the drawer path lacks a regression test for switching sessions with stored scratchlist entries.

Testing

• Not run (automation). Suggested: add a hook/component regression test that seeds sessions A and B in localStorage, rerenders with B, and asserts B storage is not overwritten by A entries.

HAPI Bot

[github-actions]

Findings

• [Major] Prevent scratchlist mode from dropping attachments — in scratchlist mode the wrapper returns success after adding only text, while HappyComposer still treats composer attachments as sendable input. A text+attachment submit therefore routes through this branch, stores only the text, and silently discards the attachment instead of sending or preserving it. Evidence web/src/components/SessionChat.tsx:205.
  Suggested fix:

  // HappyComposer.tsx
  const scratchlistMode = props.scratchlistMode ?? false
  const canSend = scratchlistMode
      ? hasText && !hasAttachments && attachmentsReady && !controlsDisabled
      : (hasText || hasAttachments) && attachmentsReady && !controlsDisabled
  
  // SessionChat.tsx
  if (scratchlistMode) {
      if ((attachments?.length ?? 0) > 0) return false
      return scratchlist.add(text)
  }

Questions

• None.

Summary

• Review mode: follow-up after new commits
• The previous cross-session scratchlist storage finding is addressed by the loaded-session state pair and regression tests. One remaining attachment-loss regression found in the new scratchlist composer routing.

Testing

• Not run (automation). Suggested: add a composer/scratchlist-mode test covering a text+attachment draft and assert the scratchlist route is rejected or the send button is disabled while attachments are present.

HAPI Bot

[github-actions]

Findings

• [Major] Clear accepted scheduled chat sends after scratchlist fallback — the follow-up change correctly falls through to props.onSend when scratchlist mode is on but scheduledAt is present, yet the accepted-send cleanup still checks only !scratchlistMode. That means a scheduled chat send made while the amber scratchlist UI is active is accepted, but pendingSchedule stays set, so the next normal send can accidentally reuse the same schedule. Evidence web/src/components/SessionChat.tsx:630.
  Suggested fix:

  const routedToScratchlist = shouldRouteToScratchlist(scratchlistMode, attachments, scheduledAt)
  const accepted = await onSendForComposer(text, attachments, scheduledAt)
  if (!accepted) return
  if (!routedToScratchlist) {
      setPendingSchedule(null)
      setForceScrollToken((token) => token + 1)
  }

Questions

• None.

Summary

• Review mode: follow-up after new commits
• The previous attachment-loss finding is addressed by falling non-text scratchlist-mode payloads back to normal chat. One remaining cleanup regression exists for scheduled sends that use that fallback path.

Testing

• Not run (automation). Suggested: add a handleSend/integration test where scratchlist mode is on, pendingSchedule is set, and shouldRouteToScratchlist falls through; assert pendingSchedule clears after accepted chat send.

HAPI Bot

[github-actions]

Findings

• [Major] Send button advertises scratchlist routing even when the submit will go to chat — shouldRouteToScratchlist correctly falls back to normal chat for attachments or scheduledAt, but UnifiedButton still turns amber and labels the action as “Send to scratchlist” whenever scratchlistMode is true. A scheduled send or attachment send made in that state will be submitted to chat while the UI says it is being stashed, which can send content to the agent unexpectedly. Evidence web/src/components/AssistantChat/ComposerButtons.tsx:379.
  Suggested fix:

  const routesToScratchlist = scratchlistMode && !props.hasAttachments && props.pendingSchedule == null
  
  // pass routesToScratchlist to UnifiedButton instead of raw scratchlistMode,
  // or compute it inside UnifiedButton from these props.
  <UnifiedButton
      ...
      scratchlistMode={routesToScratchlist}
  />

Questions

• None.

Summary

• Review mode: follow-up after new commits
• The previous bot finding about scheduled-send cleanup is addressed at the current head. One remaining correctness issue: the composer button state can still claim scratchlist routing while the actual send path falls back to chat for scheduled/attached payloads.

Testing

• Not run: bun is unavailable in this runner (bun: command not found). Suggested coverage: a ComposerButtons/SessionChat case with scratchlistMode=true plus pendingSchedule or attachments asserting the send button uses normal chat labeling/state.

HAPI Bot

[heavygee]

Caught on the new pass — fixed in 620df08. ScratchlistDrawerHost now calls onExitScratchlistMode whenever it promotes an entry to the composer (since promoting means "send this for real now"). Promote-to-queue still does NOT exit the mode because the queue path bypasses the wrapper anyway, and the operator may still be capturing related notes.

Exported ScratchlistDrawerHost so its host-level wiring can be unit-tested directly. Added SessionChat.exit-mode.test.tsx with 2 tests: promote-to-composer fires both setText and onExitScratchlistMode; promote-to-queue fires onSend but does NOT touch the mode.

Web suite 768/768 green; typecheck clean.

Side note: this finding only showed up in the workflow log (Review posted to GitHub for PR #798 at b256fe5...) -- the corresponding review object isn't surfaced via the REST API at the moment, so my watcher loop (hapi-pr-watch -> hapi-pr-status) couldn't see it. Reading the workflow run output directly is what surfaced it. I'll harden the loop to read the action's stdout when no fresh review is found.

[github-actions]

Findings

• No findings.

Questions

• None.

Summary

• Review mode: follow-up after new commits
• No issues found in the current diff. Prior bot finding about the send button/scratchlist routing mismatch is addressed at web/src/components/AssistantChat/ComposerButtons.tsx:632, with targeted coverage added for that contract and for promote-to-composer mode exit.
• Residual risk: tests were not executed in this review context.

Testing

• Not run (automation; review-only).

HAPI Bot

[github-actions]

Findings

• [Major] Global scratchlist hotkey fires while other controls/modals are focused — The new window listener accepts Ctrl/Cmd+Shift+S for every event target and immediately prevents default/toggles scratchlist mode. SessionChat can have focused inputs in overlays such as rename or schedule dialogs; pressing that shortcut there can turn scratchlist mode on behind the modal, so the next composer send may be routed to scratchlist instead of chat. Evidence web/src/components/SessionChat.tsx:265.
  Suggested fix:

  function isScratchlistHotkeyBlockedTarget(target: EventTarget | null): boolean {
      if (!(target instanceof HTMLElement)) return false
      if (target.closest('[role="dialog"]')) return true
      return target instanceof HTMLInputElement
          || target instanceof HTMLSelectElement
          || target.isContentEditable
  }
  
  useEffect(() => {
      const onKeyDown = (e: globalThis.KeyboardEvent) => {
          if (!isScratchlistToggleHotkey(e)) return
          if (isScratchlistHotkeyBlockedTarget(e.target)) return
          e.preventDefault()
          setScratchlistMode((m) => !m)
      }
      window.addEventListener('keydown', onKeyDown)
      return () => window.removeEventListener('keydown', onKeyDown)
  }, [])

Questions

• None.

Summary

• Review mode: follow-up after new commits
• Found one issue in the latest full diff: the scratchlist global shortcut needs to ignore dialog/form targets before toggling mode.
• Residual risk: I did not execute the web test suite in this review context.

Testing

• Suggested: add an RTL test that dispatches Ctrl/Cmd+Shift+S from an input inside a dialog and asserts scratchlist mode does not toggle; keep the existing composer/global toggle coverage.
• Not run (automation; review-only).

HAPI Bot

[github-actions]

Findings

• No issues found in the current full diff.

Questions

• None.

Summary

• Review mode: follow-up after new commits
• The prior HAPI Bot shortcut concern is addressed in the current head with target filtering for dialog/input/contentEditable focus and focused unit coverage.
• Residual risk: no browser/e2e run in this review context; FUE popover placement and composer drawer behavior still rely on existing/manual browser coverage.

Testing

• Not run (automation; review-only).

HAPI Bot

[github-actions]

Findings

• [Major] Session switch can show the previous session's scratchlist — scratchlistMode is reset in an effect, and useScratchlist also rehydrates in an effect. When SessionChat is reused for /sessions/A -> /sessions/B, the first B render can still have A's scratchlistMode and A's entries/counter before those effects run, exposing or acting on notes from the wrong session. Evidence web/src/components/SessionChat.tsx:274 and web/src/lib/use-scratchlist.ts:51.
  Suggested fix:

  type SessionChatProps = {
      // existing props object
  }
  
  export function SessionChat(props: SessionChatProps) {
      return <SessionChatInner key={props.session.id} {...props} />
  }
  
  function SessionChatInner(props: SessionChatProps) {
      const scratchlist = useScratchlist(props.session.id)
      const [scratchlistMode, setScratchlistMode] = useState(false)
      // existing implementation; remove the effect-only session reset
  }

Questions

• None.

Summary

• Review mode: follow-up after new commits
• One issue found: session changes need a synchronous remount/reset for the newly lifted scratchlist state.

Testing

• Not run: bun is not installed in this runner (bun: command not found).

HAPI Bot

[github-actions]

Findings

• No issues found.

Questions

• None.

Summary

• Review mode: follow-up after new commits
• Re-reviewed the full current diff and the previous bot finding. The new keyed SessionChatInner wrapper addresses the session-switch scratchlist exposure by remounting per-session state synchronously. No additional high-confidence issues found in the scratchlist drawer/FUE changes. Residual risk: I could not execute the web Vitest suite in this runner.

Testing

• Not run: bun is not installed in this runner (bun: command not found).
• Static check run: git diff --check 59c29e842313811a2744c6cc993de33e3bb14657..refs/remotes/origin/pr-798.

HAPI Bot