feat: bot callback URL params with componentized toolbar buttons (#416)

Adds ?cb=<encoded_url>&ct=<token> URL params for bot-initiated plan review callbacks.
When a bot posts a Plannotator share link with these params, Approve/Feedback buttons
appear and POST the user's decision (with annotated plan URL) back to the bot.

Changes:
- callback.ts: parse callback config from URL search/hash params, execute POST
- ToolbarButtons.tsx: extract shared FeedbackButton/ApproveButton components (6 instances → 2 components)
- sharing.ts: strip ?cb=&ct= from hash before decompressing share payload
- App.tsx: callback buttons gated on isSharedSession + shareUrl readiness
- 19 tests covering config parsing, URL validation, presigned URL preservation, and POST execution

Co-authored-by: aviadshiber <aviadshiber@users.noreply.github.com>

For provenance purposes, this commit was AI assisted.

Author: aviadshiber

packages/editor/App.tsx

@@ -13,7 +13,9 @@ import { AnnotationToolstrip } from '@plannotator/ui/components/AnnotationToolst
 import { TaterSpriteRunning } from '@plannotator/ui/components/TaterSpriteRunning';
 import { TaterSpritePullup } from '@plannotator/ui/components/TaterSpritePullup';
 import { Settings } from '@plannotator/ui/components/Settings';
+import { FeedbackButton, ApproveButton } from '@plannotator/ui/components/ToolbarButtons';
 import { useSharing } from '@plannotator/ui/hooks/useSharing';
+import { getCallbackConfig, CallbackAction, executeCallback, type ToastPayload } from '@plannotator/ui/utils/callback';
 import { useAgents } from '@plannotator/ui/hooks/useAgents';
 import { useActiveSection } from '@plannotator/ui/hooks/useActiveSection';
 import { storage } from '@plannotator/ui/utils/storage';
@@ -115,7 +117,7 @@ const App: React.FC = () => {
 
   const [showExportDropdown, setShowExportDropdown] = useState(false);
   const [initialExportTab, setInitialExportTab] = useState<'share' | 'annotations' | 'notes'>();
-  const [noteSaveToast, setNoteSaveToast] = useState<{ type: 'success' | 'error'; message: string } | null>(null);
+  const [noteSaveToast, setNoteSaveToast] = useState<ToastPayload>(null);
   const [isPlanDiffActive, setIsPlanDiffActive] = useState(false);
   const [planDiffMode, setPlanDiffMode] = useState<PlanDiffMode>('clean');
   const [previousPlan, setPreviousPlan] = useState<string | null>(null);
@@ -924,6 +926,29 @@ const App: React.FC = () => {
     return output;
   }, [blocks, allAnnotations, globalAttachments, linkedDocHook.getDocAnnotations, editorAnnotations]);
 
+  // Bot callback config — read once from URL search params (?cb=&ct=)
+  const callbackConfig = React.useMemo(() => getCallbackConfig(), []);
+
+  const callCallback = React.useCallback(async (action: CallbackAction) => {
+    if (!callbackConfig || isSubmitting || !shareUrl) return;
+    setIsSubmitting(true);
+    try {
+      const toast = await executeCallback(action, callbackConfig, shareUrl);
+      if (toast) {
+        setNoteSaveToast(toast);
+        setTimeout(() => setNoteSaveToast(null), 4000);
+        if (toast.type === 'success') {
+          setSubmitted(action === CallbackAction.Approve ? 'approved' : 'denied');
+        }
+      }
+    } finally {
+      setIsSubmitting(false);
+    }
+  }, [callbackConfig, isSubmitting, shareUrl]);
+
+  const handleCallbackApprove = React.useCallback(() => callCallback(CallbackAction.Approve), [callCallback]);
+  const handleCallbackFeedback = React.useCallback(() => callCallback(CallbackAction.Feedback), [callCallback]);
+
   // Quick-save handlers for export dropdown and keyboard shortcut
   const handleDownloadAnnotations = () => {
     setShowExportDropdown(false);
@@ -1109,6 +1134,25 @@ const App: React.FC = () => {
           </div>
 
           <div className="flex items-center gap-1 md:gap-2">
+            {/* Bot callback buttons — only shown when ?cb=&ct= params are present */}
+            {callbackConfig && !isApiMode && isSharedSession && (
+              <>
+                <div className="w-px h-5 bg-border/50 mx-1 hidden md:block" />
+                <FeedbackButton
+                  onClick={handleCallbackFeedback}
+                  disabled={isSubmitting || !shareUrl}
+                  isLoading={isSubmitting}
+                  title="Send feedback to bot"
+                />
+                <ApproveButton
+                  onClick={handleCallbackApprove}
+                  disabled={isSubmitting || !shareUrl}
+                  isLoading={isSubmitting}
+                  title="Approve design and notify bot"
+                />
+              </>
+            )}
+
             {isApiMode && !linkedDocHook.isActive && archive.archiveMode && (
               <>
                 <button
@@ -1133,7 +1177,7 @@ const App: React.FC = () => {
 
             {isApiMode && !linkedDocHook.isActive && !archive.archiveMode && (
               <>
-                <button
+                <FeedbackButton
                   onClick={() => {
                     if (annotateMode) {
                       handleAnnotateFeedback();
@@ -1150,29 +1194,18 @@ const App: React.FC = () => {
                     }
                   }}
                   disabled={isSubmitting}
-                  className={`p-1.5 md:px-2.5 md:py-1 rounded-md text-xs font-medium transition-all ${
-                    isSubmitting
-                      ? 'opacity-50 cursor-not-allowed bg-muted text-muted-foreground'
-                      : 'bg-accent/15 text-accent hover:bg-accent/25 border border-accent/30'
-                  }`}
+                  isLoading={isSubmitting}
+                  label={annotateMode ? (allAnnotations.length > 0 || editorAnnotations.length > 0 || linkedDocHook.docAnnotationCount > 0 ? 'Send Annotations' : 'Done') : 'Send Feedback'}
                   title={annotateMode ? (allAnnotations.length > 0 || editorAnnotations.length > 0 || linkedDocHook.docAnnotationCount > 0 ? 'Send Annotations' : 'Done') : 'Send Feedback'}
-                >
-                  <svg className="w-4 h-4 md:hidden" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
-                    <path strokeLinecap="round" strokeLinejoin="round" d="M8 12h.01M12 12h.01M16 12h.01M21 12c0 4.418-4.03 8-9 8a9.863 9.863 0 01-4.255-.949L3 20l1.395-3.72C3.512 15.042 3 13.574 3 12c0-4.418 4.03-8 9-8s9 3.582 9 8z" />
-                  </svg>
-                  <span className="hidden md:inline">{isSubmitting ? 'Sending...' : annotateMode ? (allAnnotations.length > 0 || editorAnnotations.length > 0 || linkedDocHook.docAnnotationCount > 0 ? 'Send Annotations' : 'Done') : 'Send Feedback'}</span>
-                </button>
+                />
 
                 {!annotateMode && <div className="relative group/approve">
-                  <button
+                  <ApproveButton
                     onClick={() => {
-                      // Show warning for Claude Code users with annotations
                       if (origin === 'claude-code' && allAnnotations.length > 0) {
                         setShowClaudeCodeWarning(true);
                         return;
                       }
-
-                      // Check if agent exists for OpenCode users
                       if (origin === 'opencode') {
                         const warning = getAgentWarning();
                         if (warning) {
@@ -1181,21 +1214,12 @@ const App: React.FC = () => {
                           return;
                         }
                       }
-
                       handleApprove();
                     }}
                     disabled={isSubmitting}
-                    className={`px-2 py-1 md:px-2.5 rounded-md text-xs font-medium transition-all ${
-                      isSubmitting
-                        ? 'opacity-50 cursor-not-allowed bg-muted text-muted-foreground'
-                        : origin === 'claude-code' && allAnnotations.length > 0
-                          ? 'bg-success/50 text-success-foreground/70 hover:bg-success hover:text-success-foreground'
-                          : 'bg-success text-success-foreground hover:opacity-90'
-                    }`}
-                  >
-                    <span className="md:hidden">{isSubmitting ? '...' : 'OK'}</span>
-                    <span className="hidden md:inline">{isSubmitting ? 'Approving...' : 'Approve'}</span>
-                  </button>
+                    isLoading={isSubmitting}
+                    dimmed={origin === 'claude-code' && allAnnotations.length > 0}
+                  />
                   {origin === 'claude-code' && allAnnotations.length > 0 && (
                     <div className="absolute top-full right-0 mt-2 px-3 py-2 bg-popover border border-border rounded-lg shadow-xl text-xs text-foreground w-56 text-center opacity-0 invisible group-hover/approve:opacity-100 group-hover/approve:visible transition-all pointer-events-none z-50">
                       <div className="absolute bottom-full right-4 border-4 border-transparent border-b-border" />

packages/review-editor/App.tsx

@@ -4,6 +4,7 @@ import { ThemeProvider, useTheme } from '@plannotator/ui/components/ThemeProvide
 import { ModeToggle } from '@plannotator/ui/components/ModeToggle';
 import { ConfirmDialog } from '@plannotator/ui/components/ConfirmDialog';
 import { Settings } from '@plannotator/ui/components/Settings';
+import { FeedbackButton, ApproveButton } from '@plannotator/ui/components/ToolbarButtons';
 import { UpdateBanner } from '@plannotator/ui/components/UpdateBanner';
 import { storage } from '@plannotator/ui/utils/storage';
 import { CompletionOverlay } from '@plannotator/ui/components/CompletionOverlay';
@@ -1242,7 +1243,7 @@ const ReviewApp: React.FC = () => {
                 )}
 
                 {/* Send Feedback button — always the same label */}
-                <button
+                <FeedbackButton
                   onClick={() => {
                     if (platformMode) {
                       setPlatformGeneralComment('');
@@ -1255,28 +1256,16 @@ const ReviewApp: React.FC = () => {
                     isSendingFeedback || isApproving || isPlatformActioning ||
                     (!platformMode && totalAnnotationCount === 0)
                   }
-                  className={`p-1.5 md:px-2.5 md:py-1 rounded-md text-xs font-medium transition-all ${
-                    isSendingFeedback || isApproving || isPlatformActioning
-                      ? 'opacity-50 cursor-not-allowed bg-muted text-muted-foreground'
-                      : !platformMode && totalAnnotationCount === 0
-                        ? 'opacity-50 cursor-not-allowed bg-accent/10 text-accent/50'
-                        : 'bg-accent/15 text-accent hover:bg-accent/25 border border-accent/30'
-                  }`}
+                  isLoading={isSendingFeedback || isPlatformActioning}
+                  muted={!platformMode && totalAnnotationCount === 0 && !isSendingFeedback && !isApproving && !isPlatformActioning}
+                  label={platformMode ? 'Post Comments' : 'Send Feedback'}
+                  loadingLabel={platformMode ? 'Posting...' : 'Sending...'}
                   title={!platformMode && totalAnnotationCount === 0 ? "Add annotations to send feedback" : "Send feedback"}
-                >
-                  <svg className="w-4 h-4 md:hidden" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
-                    <path strokeLinecap="round" strokeLinejoin="round" d="M8 12h.01M12 12h.01M16 12h.01M21 12c0 4.418-4.03 8-9 8a9.863 9.863 0 01-4.255-.949L3 20l1.395-3.72C3.512 15.042 3 13.574 3 12c0-4.418 4.03-8 9-8s9 3.582 9 8z" />
-                  </svg>
-                  <span className="hidden md:inline">{
-                    isSendingFeedback || isPlatformActioning
-                      ? (platformMode ? 'Posting...' : 'Sending...')
-                      : (platformMode ? 'Post Comments' : 'Send Feedback')
-                  }</span>
-                </button>
+                />
 
                 {/* Approve button — always the same label */}
                 <div className="relative group/approve">
-                  <button
+                  <ApproveButton
                     onClick={() => {
                       if (platformMode) {
                         if (platformUser && prMetadata?.author === platformUser) return;
@@ -1294,24 +1283,15 @@ const ReviewApp: React.FC = () => {
                       isSendingFeedback || isApproving || isPlatformActioning ||
                       (platformMode && !!platformUser && prMetadata?.author === platformUser)
                     }
-                    className={`px-2 py-1 md:px-2.5 rounded-md text-xs font-medium transition-all ${
-                      isSendingFeedback || isApproving || isPlatformActioning
-                        ? 'opacity-50 cursor-not-allowed bg-muted text-muted-foreground'
-                        : platformMode && platformUser && prMetadata?.author === platformUser
-                          ? 'opacity-40 cursor-not-allowed bg-muted text-muted-foreground'
-                          : !platformMode && totalAnnotationCount > 0
-                            ? 'bg-success/50 text-success-foreground/70 hover:bg-success hover:text-success-foreground'
-                            : 'bg-success text-success-foreground hover:opacity-90'
-                    }`}
+                    isLoading={isApproving}
+                    dimmed={!platformMode && totalAnnotationCount > 0}
+                    muted={platformMode && !!platformUser && prMetadata?.author === platformUser && !isSendingFeedback && !isApproving && !isPlatformActioning}
                     title={
                       platformMode && platformUser && prMetadata?.author === platformUser
                         ? `You can't approve your own ${mrLabel}`
                         : "Approve - no changes needed"
                     }
-                  >
-                    <span className="md:hidden">{isApproving ? '...' : 'OK'}</span>
-                    <span className="hidden md:inline">{isApproving ? 'Approving...' : 'Approve'}</span>
-                  </button>
+                  />
                   {/* Tooltip: own PR warning OR annotations-lost warning */}
                   {platformMode && platformUser && prMetadata?.author === platformUser ? (
                     <div className="absolute top-full right-0 mt-2 px-3 py-2 bg-popover border border-border rounded-lg shadow-xl text-xs text-foreground w-48 text-center opacity-0 invisible group-hover/approve:opacity-100 group-hover/approve:visible transition-all pointer-events-none z-50">

packages/ui/components/ToolbarButtons.tsx

@@ -0,0 +1,83 @@
+import React from 'react';
+
+interface FeedbackButtonProps {
+  onClick: () => void;
+  disabled?: boolean;
+  isLoading?: boolean;
+  label?: string;
+  loadingLabel?: string;
+  title?: string;
+  muted?: boolean;
+}
+
+export const FeedbackButton: React.FC<FeedbackButtonProps> = ({
+  onClick,
+  disabled = false,
+  isLoading = false,
+  label = 'Send Feedback',
+  loadingLabel = 'Sending...',
+  title = 'Send Feedback',
+  muted = false,
+}) => (
+  <button
+    onClick={onClick}
+    disabled={disabled}
+    className={`p-1.5 md:px-2.5 md:py-1 rounded-md text-xs font-medium transition-all ${
+      muted
+        ? 'opacity-50 cursor-not-allowed bg-accent/10 text-accent/50'
+        : disabled
+          ? 'opacity-50 cursor-not-allowed bg-muted text-muted-foreground'
+          : 'bg-accent/15 text-accent hover:bg-accent/25 border border-accent/30'
+    }`}
+    title={title}
+  >
+    <svg className="w-4 h-4 md:hidden" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
+      <path strokeLinecap="round" strokeLinejoin="round" d="M8 12h.01M12 12h.01M16 12h.01M21 12c0 4.418-4.03 8-9 8a9.863 9.863 0 01-4.255-.949L3 20l1.395-3.72C3.512 15.042 3 13.574 3 12c0-4.418 4.03-8 9-8s9 3.582 9 8z" />
+    </svg>
+    <span className="hidden md:inline">{isLoading ? loadingLabel : label}</span>
+  </button>
+);
+
+interface ApproveButtonProps {
+  onClick: () => void;
+  disabled?: boolean;
+  isLoading?: boolean;
+  label?: string;
+  loadingLabel?: string;
+  mobileLabel?: string;
+  mobileLoadingLabel?: string;
+  title?: string;
+  dimmed?: boolean;
+  muted?: boolean;
+}
+
+export const ApproveButton: React.FC<ApproveButtonProps> = ({
+  onClick,
+  disabled = false,
+  isLoading = false,
+  label = 'Approve',
+  loadingLabel = 'Approving...',
+  mobileLabel = 'OK',
+  mobileLoadingLabel = '...',
+  title,
+  dimmed = false,
+  muted = false,
+}) => (
+  <button
+    onClick={onClick}
+    disabled={disabled}
+    className={`px-2 py-1 md:px-2.5 rounded-md text-xs font-medium transition-all ${
+      muted
+        ? 'opacity-40 cursor-not-allowed bg-muted text-muted-foreground'
+        : disabled
+          ? 'opacity-50 cursor-not-allowed bg-muted text-muted-foreground'
+          : dimmed
+            ? 'bg-success/50 text-success-foreground/70 hover:bg-success hover:text-success-foreground'
+            : 'bg-success text-success-foreground hover:opacity-90'
+    }`}
+    title={title}
+  >
+    <span className="md:hidden">{isLoading ? mobileLoadingLabel : mobileLabel}</span>
+    <span className="hidden md:inline">{isLoading ? loadingLabel : label}</span>
+  </button>
+);