@prenta/admin 1.15.0 → 1.17.0

package/src/views/seo/ProposalsTab.tsx

@@ -5,9 +5,11 @@
  * in one review surface. Batch approve honours server governance
  * (`allowBulkApply`); the UI only pre-disables the button using the flags the
  * list payload exposes. Generation is human-triggered, capped per pass, and
- * loops client-side while the server reports `remaining > 0`.
+ * loops client-side while the server reports `remaining > 0`. FAQ
+ * (`add-section`) rows expand into a per-question preview and approve one at
+ * a time through `apply-fix`; in a batch they apply the whole drafted section.
  */
-import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
+import { useCallback, useEffect, useId, useMemo, useRef, useState, type ReactNode } from 'react'
 import {
   AlertTriangle,
   ArrowRightLeft,
@@ -22,11 +24,13 @@ import {
 } from 'lucide-react'
 import { toast } from 'sonner'
 import {
+  applySeoIssueFix,
   bulkApplySeoProposals,
   dismissRedirectSuggestion,
   dismissSeoIssueFix,
   fetchSeoProposals,
   generateSeoProposals,
+  type SeoApplyFixOptions,
   type SeoProposal,
   type SeoProposalBulkApplyItem,
   type SeoProposalsPayload,
@@ -35,6 +39,11 @@ import { hasPlanFeature, type PlanInfo } from '../../lib/plan.js'
 import { brandAlignmentLabel, brandAlignmentTone } from '../../lib/brand-voice-client.js'
 import { PlanUpgradeCallout } from '../../components/PlanUpgradeCallout.js'
 import { ChangePreview } from '../../components/seo/ChangePreview.js'
+import {
+  FaqProposalPreview,
+  faqDraftBlocker,
+  faqSignalLine,
+} from '../../components/seo/FaqProposalPreview.js'
 import {
   SectionCard,
   SeoEmptyState,
@@ -76,6 +85,77 @@ function toBulkItem(p: SeoProposal): SeoProposalBulkApplyItem {
     : { kind: 'issue-fix', id: p.issueId ?? '', fingerprint: p.fingerprint ?? undefined }
 }
 
+/** An `add-section` (FAQ) proposal; `p.section` may still be `null` when the cache was unreadable. */
+function isFaqProposal(p: SeoProposal): boolean {
+  return p.fixStrategy === 'add-section'
+}
+
+/**
+ * Reviewer edits to a FAQ proposal before approval. `selected` is parallel to
+ * `section.content.items`; `heading` is the raw input value (trimmed on send).
+ */
+interface FaqDraft {
+  selected: boolean[]
+  heading: string
+}
+
+/**
+ * Drafts are keyed by the drafted content, not just the issue: `fingerprint`
+ * tracks the page (`updatedAt`), so dismiss + regenerate on an unchanged page
+ * keeps the same id and fingerprint while the questions change. Folding the
+ * questions (and `generatedAt`) into the key makes a regenerated proposal
+ * start clean instead of inheriting stale ticks or a stale heading edit.
+ */
+function faqDraftKey(p: SeoProposal): string {
+  const questions = p.section?.content.items.map((i) => i.question).join('\u0001') ?? ''
+  return `${p.id}:${p.generatedAt ?? ''}:${questions}`
+}
+
+function initialFaqDraft(p: SeoProposal): FaqDraft {
+  const section = p.section
+  return {
+    selected: section ? section.content.items.map(() => true) : [],
+    heading: section?.content.heading ?? '',
+  }
+}
+
+/**
+ * The row's stored draft when it still fits the section (one `selected` flag
+ * per item), otherwise the untouched default. Every reader *and* writer goes
+ * through this so a mismatched draft is replaced rather than mutated.
+ */
+function currentFaqDraft(drafts: Record<string, FaqDraft>, p: SeoProposal): FaqDraft {
+  const draft = drafts[faqDraftKey(p)]
+  if (draft && draft.selected.length === (p.section?.content.items.length ?? 0)) return draft
+  return initialFaqDraft(p)
+}
+
+/**
+ * Body of the single-row `apply-fix` call. `includeItems` only when the
+ * reviewer dropped a question; `headingOverride` only when the trimmed heading
+ * is non-empty and differs from the draft — so an untouched row sends exactly
+ * `{ fingerprint }`, the same request the Audit tab makes.
+ */
+function faqApplyOptions(p: SeoProposal, draft: FaqDraft): SeoApplyFixOptions {
+  const opts: SeoApplyFixOptions = {}
+  const includeItems = draft.selected.flatMap((on, i) => (on ? [i] : []))
+  if (includeItems.length < draft.selected.length) opts.includeItems = includeItems
+  const heading = draft.heading.trim()
+  if (heading !== '' && heading !== p.section?.content.heading) opts.headingOverride = heading
+  return opts
+}
+
+/** Change-column text for a FAQ row: question count plus the strongest signal. */
+function faqSummary(p: SeoProposal): string {
+  const signal = faqSignalLine(p.signals)
+  if (!p.section) return signal ?? p.justification
+  const count = plural(p.section.content.items.length, 'question')
+  return signal ? `${count} · ${signal}` : count
+}
+
+const FAQ_UNREADABLE_HINT =
+  'The drafted section could not be read from the cache. Dismiss this proposal and generate again to get a fresh draft.'
+
 function BrandScoreBadge({ score }: { score: number }) {
   return (
     <span
@@ -187,6 +267,8 @@ export function ProposalsTab({
   const [confirmGenerate, setConfirmGenerate] = useState(false)
   const [mutation, setMutation] = useState<Mutation | null>(null)
   const [pendingItems, setPendingItems] = useState<SeoProposalBulkApplyItem[]>([])
+  /** Per-row FAQ review edits, created lazily on first interaction (see `faqDraftKey`). */
+  const [faqDrafts, setFaqDrafts] = useState<Record<string, FaqDraft>>({})
   const [generating, setGenerating] = useState<{ done: number; total: number } | null>(null)
   /** Bumped after every mutation so the autopilot ledger below refetches with the inbox. */
   const [refreshKey, setRefreshKey] = useState(0)
@@ -305,6 +387,70 @@ export function ProposalsTab({
     [afterMutation, beginMutation, endMutation],
   )
 
+  /** The row's current draft, or the untouched default when the reviewer has not edited it. */
+  const faqDraftFor = useCallback(
+    (p: SeoProposal): FaqDraft => currentFaqDraft(faqDrafts, p),
+    [faqDrafts],
+  )
+  const toggleFaqItem = useCallback((p: SeoProposal, index: number) => {
+    setFaqDrafts((cur) => {
+      const base = currentFaqDraft(cur, p)
+      const selected = base.selected.map((on, i) => (i === index ? !on : on))
+      return { ...cur, [faqDraftKey(p)]: { ...base, selected } }
+    })
+  }, [])
+  const setFaqHeading = useCallback((p: SeoProposal, heading: string) => {
+    setFaqDrafts((cur) => ({ ...cur, [faqDraftKey(p)]: { ...currentFaqDraft(cur, p), heading } }))
+  }, [])
+
+  // Drop drafts whose proposal is gone or was regenerated, so the map cannot grow across refetches.
+  useEffect(() => {
+    const liveKeys = new Set(proposals.filter(isFaqProposal).map(faqDraftKey))
+    setFaqDrafts((cur) => {
+      const stale = Object.keys(cur).filter((key) => !liveKeys.has(key))
+      if (stale.length === 0) return cur
+      const next = { ...cur }
+      for (const key of stale) delete next[key]
+      return next
+    })
+  }, [proposals])
+
+  /**
+   * Single-row approve for a FAQ proposal. Goes through `apply-fix` (not
+   * bulk-apply) so the reviewer's per-question selection and heading edit are
+   * honoured; the bulk path applies the whole drafted section unchanged.
+   */
+  const handleApproveFaq = useCallback(
+    async (p: SeoProposal) => {
+      if (!p.issueId || !p.fingerprint || !p.section) return
+      const draft = faqDraftFor(p)
+      if (faqDraftBlocker(draft.selected) !== null) return
+      if (!beginMutation('apply')) return
+      try {
+        const res = await applySeoIssueFix(p.issueId, p.fingerprint, faqApplyOptions(p, draft))
+        if (!mountedRef.current) return
+        if (res.error) {
+          toast.error(res.error)
+          return
+        }
+        toast.success('FAQ section added.')
+        setFaqDrafts((cur) => {
+          const key = faqDraftKey(p)
+          if (!(key in cur)) return cur
+          const rest = { ...cur }
+          delete rest[key]
+          return rest
+        })
+        afterMutation()
+      } catch (err) {
+        if (mountedRef.current) toast.error(errorMessage(err))
+      } finally {
+        endMutation()
+      }
+    },
+    [afterMutation, beginMutation, endMutation, faqDraftFor],
+  )
+
   const handleDismissSelected = useCallback(async () => {
     const targets = selectedProposals
     if (targets.length === 0) return
@@ -573,6 +719,41 @@ export function ProposalsTab({
                 <tbody className="divide-border divide-y">
                   {proposals.map((p) => {
                     const first = p.changes[0]
+                    const canApply = inlineApplyEnabled || p.kind === 'redirect'
+                    if (isFaqProposal(p)) {
+                      const draft = faqDraftFor(p)
+                      const blocker = p.section
+                        ? faqDraftBlocker(draft.selected)
+                        : FAQ_UNREADABLE_HINT
+                      return (
+                        <ProposalRow
+                          key={p.id}
+                          proposal={p}
+                          selected={selected.has(p.id)}
+                          expanded={expanded.has(p.id)}
+                          summary={faqSummary(p)}
+                          onToggleSelect={() => toggleSelect(p.id)}
+                          onToggleExpanded={() => toggleExpanded(p.id)}
+                          onApprove={() => void handleApproveFaq(p)}
+                          onDismiss={() => void handleDismissOne(p)}
+                          busy={busy}
+                          canApply={canApply}
+                          approveBlocker={blocker}
+                          details={
+                            <FaqProposalDetails
+                              proposal={p}
+                              draft={draft}
+                              blocker={blocker}
+                              busy={busy}
+                              canApply={canApply}
+                              onToggle={(i) => toggleFaqItem(p, i)}
+                              onHeadingChange={(h) => setFaqHeading(p, h)}
+                              onApprove={() => void handleApproveFaq(p)}
+                            />
+                          }
+                        />
+                      )
+                    }
                     return (
                       <ProposalRow
                         key={p.id}
@@ -589,7 +770,7 @@ export function ProposalsTab({
                         onApprove={() => void runApply([toBulkItem(p)])}
                         onDismiss={() => void handleDismissOne(p)}
                         busy={busy}
-                        canApply={inlineApplyEnabled || p.kind === 'redirect'}
+                        canApply={canApply}
                       />
                     )
                   })}
@@ -637,6 +818,8 @@ function ProposalRow({
   onDismiss,
   busy,
   canApply,
+  approveBlocker = null,
+  details,
 }: {
   proposal: SeoProposal
   selected: boolean
@@ -648,7 +831,16 @@ function ProposalRow({
   onDismiss: () => void
   busy: boolean
   canApply: boolean
+  /**
+   * Why the row-level Approve is disabled (FAQ rows). Exposed as the button's
+   * tooltip and accessible description so the reason is available while the
+   * row is collapsed, not only in the expanded body.
+   */
+  approveBlocker?: string | null
+  /** Replaces the default before/after table in the expanded row. */
+  details?: ReactNode
 }) {
+  const approveHintId = `${useId()}-approve-hint`
   return (
     <>
       <tr className={`${selected ? 'bg-accent/30' : ''} hover:bg-accent/20 transition-colors`}>
@@ -666,6 +858,7 @@ function ProposalRow({
         <td className="px-3 py-3 align-top">
           <div className="flex flex-wrap items-center gap-2">
             <span className="text-foreground font-medium">{p.title}</span>
+            {isFaqProposal(p) ? <SeoStatusBadge label="FAQ section" tone="neutral" /> : null}
             {p.severity ? (
               <SeoStatusBadge
                 label={p.severity}
@@ -724,15 +917,24 @@ function ProposalRow({
         <td className="px-3 py-3 align-top">
           <div className="flex items-center justify-end gap-1">
             {!p.stale && canApply ? (
-              <button
-                type="button"
-                onClick={onApprove}
-                disabled={busy}
-                className="text-success hover:bg-accent focus-visible:ring-ring rounded-md p-1.5 focus-visible:ring-2 focus-visible:outline-none disabled:opacity-60"
-                aria-label={`Approve ${p.title}`}
-              >
-                <Check className="h-4 w-4" aria-hidden />
-              </button>
+              <>
+                <button
+                  type="button"
+                  onClick={onApprove}
+                  disabled={busy || approveBlocker !== null}
+                  className="text-success hover:bg-accent focus-visible:ring-ring rounded-md p-1.5 focus-visible:ring-2 focus-visible:outline-none disabled:opacity-60"
+                  aria-label={`Approve ${p.title}`}
+                  title={approveBlocker ?? undefined}
+                  aria-describedby={approveBlocker ? approveHintId : undefined}
+                >
+                  <Check className="h-4 w-4" aria-hidden />
+                </button>
+                {approveBlocker ? (
+                  <span id={approveHintId} className="sr-only">
+                    {approveBlocker}
+                  </span>
+                ) : null}
+              </>
             ) : null}
             <button
               type="button"
@@ -751,7 +953,7 @@ function ProposalRow({
           <td colSpan={6} className="bg-muted/30 px-4 py-4">
             <div className="space-y-3">
               <p className="text-foreground text-sm">{p.justification}</p>
-              <ChangePreview changes={p.changes} />
+              {details ?? <ChangePreview changes={p.changes} />}
             </div>
           </td>
         </tr>
@@ -759,3 +961,67 @@ function ProposalRow({
     </>
   )
 }
+
+/**
+ * Expanded body of a FAQ row: the per-question preview plus a reviewed
+ * Approve button. When core could not read the cached section the row shows
+ * the recovery hint instead of a preview and offers no approve at all.
+ */
+function FaqProposalDetails({
+  proposal: p,
+  draft,
+  blocker,
+  busy,
+  canApply,
+  onToggle,
+  onHeadingChange,
+  onApprove,
+}: {
+  proposal: SeoProposal
+  draft: FaqDraft
+  blocker: string | null
+  busy: boolean
+  canApply: boolean
+  onToggle: (index: number) => void
+  onHeadingChange: (value: string) => void
+  onApprove: () => void
+}) {
+  const section = p.section
+  if (!section) {
+    return (
+      <p className="text-muted-foreground flex items-start gap-2 text-sm">
+        <AlertTriangle className="text-warning mt-0.5 h-4 w-4 shrink-0" aria-hidden />
+        <span>{FAQ_UNREADABLE_HINT}</span>
+      </p>
+    )
+  }
+  const items = section.content.items.map((item, i) => ({
+    ...item,
+    sourceQuote: p.grounding?.[i]?.sourceQuote || undefined,
+  }))
+  return (
+    <div className="space-y-4">
+      <FaqProposalPreview
+        heading={section.content.heading}
+        items={items}
+        signals={p.signals}
+        selected={draft.selected}
+        onToggle={onToggle}
+        headingValue={draft.heading}
+        onHeadingChange={onHeadingChange}
+        disabled={busy}
+      />
+      {!p.stale && canApply ? (
+        <button
+          type="button"
+          className={btnPrimary}
+          onClick={onApprove}
+          disabled={busy || blocker !== null}
+        >
+          <Check className="h-4 w-4" aria-hidden />
+          Approve
+        </button>
+      ) : null}
+    </div>
+  )
+}

package/src/views/seo/TechnicalTab.tsx

@@ -323,18 +323,37 @@ const CATEGORY_LABELS: Record<string, string> = {
   other: 'Other',
 }
 
-function AiCrawlerCard() {
+function AiCrawlerCard({ onNavigate }: { onNavigate?: (path: string) => void }) {
   const { data, loading, error, refetch } = useSeoResource(fetchAiCrawlerActivity, [])
 
   return (
     <SectionCard
       title="AI crawler activity"
-      description="Known AI crawlers seen fetching llms.txt, llms-full.txt, and .md pages. This is visibility, not a traffic channel — expect modest numbers."
+      description="Lifetime fetches of llms.txt, llms-full.txt, and .md pages by known AI crawlers. Daily trends across all pages and AI referrals live in the AI visibility tab."
       action={
-        <button className={btnSecondary} onClick={() => refetch()} disabled={loading}>
-          <RefreshCw className={`h-4 w-4 ${loading ? 'animate-spin' : ''}`} aria-hidden />
-          Refresh
-        </button>
+        <div className="flex shrink-0 items-center gap-2">
+          {onNavigate && (
+            <button
+              type="button"
+              className={btnSecondary}
+              onClick={() => onNavigate('/seo/ai-visibility')}
+            >
+              View trends
+            </button>
+          )}
+          <button
+            type="button"
+            className={btnSecondary}
+            onClick={() => refetch()}
+            disabled={loading}
+          >
+            <RefreshCw
+              className={`h-4 w-4 ${loading ? 'motion-safe:animate-spin' : ''}`}
+              aria-hidden
+            />
+            Refresh
+          </button>
+        </div>
       }
     >
       {loading ? (
@@ -412,7 +431,7 @@ function AiCrawlerCard() {
   )
 }
 
-export function TechnicalTab() {
+export function TechnicalTab({ onNavigate }: { onNavigate?: (path: string) => void }) {
   return (
     <div className="space-y-4">
       <div className="grid grid-cols-1 gap-4 lg:grid-cols-2">
@@ -420,7 +439,7 @@ export function TechnicalTab() {
         <CrawlCard />
       </div>
       <RobotsCard />
-      <AiCrawlerCard />
+      <AiCrawlerCard onNavigate={onNavigate} />
     </div>
   )
 }

package/src/views/settings/SeoAutopilotCard.tsx

@@ -120,6 +120,12 @@ export const AUTOPILOT_TYPE_GROUPS: ReadonlyArray<{
         help: 'Adds the collection’s default Schema.org type.',
         producer: 'Rule-based',
       },
+      {
+        id: 'faq-schema-missing',
+        label: 'FAQ schema for visible FAQ sections',
+        help: 'Adds a FAQPage node to a page’s stored structured data when a visible FAQ section has none — typically pages published before the section was added. Re-publishing the page clears it too.',
+        producer: 'Rule-based',
+      },
     ],
   },
   {