Files
PaperClipAI/ui/src/components/IssueLinkQuicklook.tsx
T
DottaandClaude Opus 5.5 b56f240f45 feat(analytics): show session replay text by default, mask only customer content (#22057)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Hosted Paperclip Cloud records browser sessions with PostHog session
replay
> - Replay masked all text and showed only an allowlist of chrome, so
most replays showed only stars
> - The team cannot see how people use the board, and the allowlist
needed a review for each new label
> - The owner decided to show text by default and mask only marked
customer content, the way PostHog normally works
> - This pull request flips the default, removes the allowlist, and
marks every surface that can show connected-account content
> - The benefit is readable replays, while Google user data and Slack
data stay masked

## Linked Issues or Issue Description

**Subsystem affected**

Hosted Cloud browser analytics: PostHog session replay in the board UI
(`ui/src/lib/analytics/`).

**Problem or motivation**

Replay masked every text node. Only sidebar items and opt-in components
showed text. Replays were almost unreadable. Each new label needed an
`analyticsChrome` opt-in and an allowlist review.

**Proposed solution**

Record text as it is. Mask text only inside `ph-mask` (customer
content), `ph-no-capture` (secrets, blocked) and editable content. Add
`ANALYTICS_MASK_CLASS` to every surface that can show connected-account
content (Gmail, Calendar, Drive and Docs, Slack) or other free-form text
from agents or customers.

**Alternatives considered**

Keep "mask all" and grow the allowlist. This needs a review for each
label and still hides most of the board.

## What Changed

- `privacy.ts`: `ANALYTICS_MASK_TEXT_SELECTOR` is now `.ph-mask,
.ph-no-capture, [contenteditable]:not([contenteditable="false"])`. rrweb
masks a text node only when its parent or an ancestor matches the
selector. Removed `maskReplayText`, `isReplayTextRevealed`,
`ANALYTICS_UNMASK_ATTRIBUTE` and `ANALYTICS_UNMASK_PROPS`.
- `product-analytics.ts`: removed `maskTextFn`, so rrweb uses its
default star masking. `maskAllInputs`, `blockClass`, `maskAttributeFn`,
`mask_all_text` and `mask_all_element_attributes` do not change.
- Removed the `analyticsChrome` prop from `Button`, `Label`,
`TabsTrigger`, `EmptyState` and `SidebarNavItem`, and from all sidebar
call sites.
- Added `ANALYTICS_MASK_CLASS` to the content element (not the chrome)
of these surfaces:
- Link preview cards, task quicklook description, external object pills
and rows, related-work titles.
  - Email message cards and email send intents.
- Connected account names and email addresses (Browse, Connections, app
detail headers, app sidebar, connection choice list, connection access
and repair cards), GitHub login and repositories, Slack workspace names,
chat channel and linked user labels.
- Inbox and decision rows (subject and detail), obligation evidence,
Needs You notes and receipts, decision options and result summaries, and
the interaction card roots (questions, options, answers, tool action
requests, suggested tasks).
- Approval payloads, action card input and reason, recovery card
headline, evidence and options, run ledger retry detail, interrupt
handoff previews.
- Run transcripts, run failure details and run events on the agent page.
- Search result snippets, toast bodies, voice and call transcripts, case
summary, files and fields, attachment previews, artifact previews (text,
tables, patches and documents).
- Replaced `unmask-allowlist.test.ts` with `replay-masking.test.tsx`. It
checks that unmarked chrome records as it is, that each marker masks,
that a rendered voice transcript and run transcript mask, that each
surface above has the class, and that autocapture records no element
text. Updated `privacy.test.ts`, `shared-chrome.test.tsx` and
`product-analytics.test.ts`.
- Updated `doc/cloud-browser-analytics.md`: new default, marker classes,
masked surfaces, and residual risk.

## Verification

- `pnpm exec vitest run src/lib/analytics` in `ui/`: 83 tests pass.
- Vitest for the 48 test files next to the changed components: 994 tests
pass.
- `tsc --noEmit -p ui/tsconfig.json`: no new errors (only the existing
generated Storybook catalog errors).
- `pnpm verify` exits 2 because a doc is a global CI input. Required CI
supplies the broad coverage.
- Manual: I ran an isolated local instance with a Cloud-like browser
analytics config. `PAPERCLIP_POSTHOG_HOST` pointed to a local capture
server, not PostHog. I opened a task page in headless Chromium, hovered
a GitHub pull request link, and decoded the captured `/s/` replay
payloads:
- Clear text: sidebar (`New task`, `Chat`, `Tasks`, `Inbox`, `More`),
breadcrumb, task title `Quarterly launch checklist`, `REP-1`, the
Connectors promo heading and button.
- Masked (stars only): the markdown task body, the chat comment, the
link preview card (pull request title, author, URL, status), and the
company menu.
- Marker strings in the body, comment and preview never appeared in
clear text in any payload.
- The page `<title>` (task title and company name) is in the replay
head. This is accepted residual risk.

## Risks

- Text that is not marked is now recorded. Task titles, agent names,
project names, company names, routine names, artifact and document
titles, and activity rows are visible in replays. The owner accepted
this. An agent can copy email or Slack text into a task title.
- A new surface that shows connected-account content without
`ANALYTICS_MASK_CLASS` is recorded until somebody marks it.
`replay-masking.test.tsx` and the doc list the marked surfaces.
- The masking options in `posthog.init` take precedence over the PostHog
project masking settings (posthog-js 1.450), so a dashboard change
cannot unmask content. Keep the project settings empty to avoid a
console warning.
- Some masked areas also mask nearby fixed labels (for example the
interaction card buttons). This is safe.
- Analytics is off on self-hosted and local installs, so they see no
change.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.

## Model Used

- Claude Opus 5.5 (claude-opus-5-5), Anthropic, with tool use and code
execution in Claude Code.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 15:18:50 -06:00

466 lines
17 KiB
TypeScript

import * as React from "react";
import { useMemo } from "react";
import * as RouterDom from "react-router-dom";
import type { Issue } from "@paperclipai/shared";
import { useQuery, useQueryClient } from "@tanstack/react-query";
import { timeAgo } from "@/lib/timeAgo";
import { createIssueDetailPath, withIssueDetailHeaderSeed } from "@/lib/issueDetailBreadcrumb";
import {
getIssueDetailQueryOptions,
ISSUE_DETAIL_STALE_TIME_MS,
} from "@/lib/issueDetailCache";
import { ISSUE_HISTORY_HOVER_PREFETCH_DELAY_MS, useIssueNavigationPrefetch } from "@/hooks/useIssueNavigationPrefetch";
import { queryKeys } from "@/lib/queryKeys";
import { cn } from "@/lib/utils";
import { Popover, PopoverContent, PopoverTrigger } from "@/components/ui/popover";
import { StatusGlyph } from "@/components/StatusGlyph";
import { ProjectTile } from "@/components/ProjectTile";
import { useFlyoutAppearance } from "@/components/ui/flyout-appearance";
import { ANALYTICS_MASK_CLASS } from "@/lib/analytics/privacy";
/* ------------------------------------------------------------------ */
/* Single-flight quicklook store */
/* */
/* Every issue link renders its own Radix Popover. In a dense list */
/* (e.g. the Conference Room agent feed) independent per-card open */
/* state lets popovers overlap, linger, and stack — two flyouts at */
/* once, sometimes showing the wrong card. This module-level store */
/* enforces exactly one open quicklook across the whole tree: opening */
/* one closes any other. */
/* ------------------------------------------------------------------ */
let activeQuicklookId: symbol | null = null;
const quicklookListeners = new Set<() => void>();
function emitQuicklookChange() {
for (const listener of quicklookListeners) listener();
}
function openQuicklookId(id: symbol) {
if (activeQuicklookId === id) return;
activeQuicklookId = id;
emitQuicklookChange();
}
function closeQuicklookId(id: symbol) {
if (activeQuicklookId !== id) return;
activeQuicklookId = null;
emitQuicklookChange();
}
function subscribeQuicklook(listener: () => void) {
quicklookListeners.add(listener);
return () => {
quicklookListeners.delete(listener);
};
}
function useIsQuicklookOpen(id: symbol) {
return React.useSyncExternalStore(
subscribeQuicklook,
() => activeQuicklookId === id,
() => false,
);
}
/** Hover-intent delay (ms) before a quicklook opens — prevents flicker
* as the pointer crosses cards on its way somewhere else. */
const QUICKLOOK_OPEN_DELAY_MS = 120;
/**
* Distance from the quicklook's outer edge to its first column of text: the
* `p-3` padding in `QUICKLOOK_CONTENT_CLASS` (12px) plus the 1px border that
* `PopoverContent` draws. Both sit between the box edge and the content, so
* both have to be cancelled to line the text up with the trigger's.
*/
const QUICKLOOK_CONTENT_INSET_PX = 12 + 1;
/** Shared shell for every surface that renders `IssueQuicklookCard`. */
export const QUICKLOOK_CONTENT_CLASS = "w-72 p-3";
/**
* Cancel the card's own inset along the align axis, so the preview lines up
* with the *text* that opened it rather than with that text's box.
*
* Radix aligns box to box: with `align="start"` the card's left edge meets the
* trigger's left edge, which leaves the card's text pushed right by its border
* and padding — visibly off against the task key above it. Pulling the box back
* by exactly that inset puts the card's first column of text on the same
* vertical line as the trigger's. `end` needs the mirror of it; `center` has no
* edge to line up with, so it gets nothing.
*/
export function quicklookAlignOffset(align: "start" | "center" | "end" = "start"): number {
if (align === "start") return -QUICKLOOK_CONTENT_INSET_PX;
if (align === "end") return QUICKLOOK_CONTENT_INSET_PX;
return 0;
}
export type IssueQuicklookIssue = Pick<Issue, "id" | "title" | "updatedAt"> & {
identifier?: string | null;
status: string;
priority: string;
description?: string | null;
blockerAttention?: Issue["blockerAttention"];
projectId?: string | null;
project?: { name?: string | null } | null;
originKind?: string;
originId?: string | null;
};
function summarizeIssueDescription(description: string | null | undefined) {
if (!description) return null;
const summary = description
.replace(/!\[[^\]]*]\([^)]+\)/g, " ")
.replace(/\[([^\]]+)\]\([^)]+\)/g, "$1")
.replace(/[#>*_`~-]+/g, " ")
.replace(/\s+/g, " ")
.trim();
if (!summary) return null;
return summary.length > 180 ? `${summary.slice(0, 177).trimEnd()}...` : summary;
}
/** "·" between facts in the quicklook's meta and status lines. */
function QuicklookSeparator({ className }: { className?: string }) {
return (
<span className={cn("text-xs", className)} aria-hidden>
·
</span>
);
}
/** "in_review" -> "In review". The card states the status as a word, not a chip. */
function statusLabel(status: string): string {
const words = status.replace(/_/g, " ");
return words.charAt(0).toUpperCase() + words.slice(1);
}
/**
* The standard task preview card. Every hover preview of a task in the app
* renders this, so the same three rows appear in the same order everywhere:
*
* 1. meta — status glyph · task key [· project] .......... last activity
* 2. title
* 3. summary — first lines of the description
*
* The meta row splits: identity on the left, recency pinned right. Identity
* leads because a preview answers "which task is this?", and the title alone
* does not.
*
* Status carries no word of its own — the glyph is the status, exactly as it is
* on task rows and decision cards. Because that leaves shape and colour as the
* only visual signal, the glyph is given a `title`, so it renders as
* `role="img"` with the status as its accessible name. The status stays
* available to a screen reader without spending a line on it.
*
* Three shapes the row must hold, per the design mock:
* 1. no project — glyph, key, and the timestamp hard right
* 2. project — a "·" and the project tile plus name join the left group
* 3. truncation — a long project name ellipsizes; the key and the timestamp
* never do, so the two facts that identify the task survive
* at any width
*/
export function IssueQuicklookCard({
issue,
linkTo,
linkState,
compact = false,
}: {
issue: IssueQuicklookIssue;
linkTo: RouterDom.To;
linkState?: unknown;
compact?: boolean;
}) {
const appearance = useFlyoutAppearance();
const description = useMemo(() => summarizeIssueDescription(issue.description), [issue.description]);
const projectName = issue.project?.name;
return (
<div className={appearance === "refreshed" ? "task-hover-card" : cn("space-y-2", compact && "space-y-1.5")}>
<div data-slot="task-preview-meta" className="flex items-center gap-1">
<div data-slot="task-preview-identity" className="flex min-w-0 flex-1 items-center gap-1">
<StatusGlyph status={issue.status} size="md" title={statusLabel(issue.status)} />
<span data-slot="task-preview-id" className="shrink-0 font-mono text-(length:--text-micro) text-muted-foreground">
{issue.identifier ?? issue.id.slice(0, 8)}
</span>
{projectName && appearance !== "refreshed" ? (
<>
<QuicklookSeparator className="shrink-0 text-muted-foreground" />
<span
className="flex min-w-0 max-w-(--sz-12rem) flex-1 items-center gap-1 text-(length:--text-micro) text-muted-foreground"
title={projectName}
data-testid="quicklook-project"
>
<ProjectTile size="xs" />
<span className="truncate">{projectName}</span>
</span>
</>
) : null}
</div>
<span data-slot="task-preview-time" className="shrink-0 text-(length:--text-micro) text-muted-foreground">
{timeAgo(new Date(issue.updatedAt))}
</span>
</div>
<RouterDom.Link
data-slot="task-preview-title"
to={linkTo}
state={linkState ?? withIssueDetailHeaderSeed(null, issue)}
className="block text-sm font-medium leading-snug hover:underline line-clamp-2"
>
{issue.title}
</RouterDom.Link>
{description ? (
<p data-slot="task-preview-description" className={cn("text-xs leading-5 text-muted-foreground [display:-webkit-box] [-webkit-box-orient:vertical] [-webkit-line-clamp:4] overflow-hidden", ANALYTICS_MASK_CLASS)}>
{description}
</p>
) : null}
</div>
);
}
export { ISSUE_HISTORY_HOVER_PREFETCH_DELAY_MS };
export const IssueLinkQuicklook = React.forwardRef<
HTMLAnchorElement,
React.ComponentProps<typeof RouterDom.Link> & {
issuePathId: string;
disableIssueQuicklook?: boolean;
issuePrefetch?: Issue | null;
issueQuicklookSide?: React.ComponentProps<typeof PopoverContent>["side"];
issueQuicklookAlign?: React.ComponentProps<typeof PopoverContent>["align"];
}
>(function IssueLinkQuicklookImpl(
{
issuePathId,
to,
children,
className,
state,
disableIssueQuicklook = false,
issuePrefetch = null,
issueQuicklookSide = "top",
issueQuicklookAlign = "start",
onClick,
onClickCapture,
onMouseEnter,
onMouseLeave,
onPointerDown,
onFocus,
onBlur,
onTouchStart,
...props
},
ref,
) {
const queryClient = useQueryClient();
const instanceId = React.useMemo(() => Symbol("issue-quicklook"), []);
const open = useIsQuicklookOpen(instanceId);
const openTimerRef = React.useRef<ReturnType<typeof setTimeout> | null>(null);
const triggerRef = React.useRef<HTMLAnchorElement | null>(null);
const contentRef = React.useRef<HTMLDivElement | null>(null);
// Keep the caller's ref working while we also hold our own handle on the
// trigger node (needed by the pointer-escape guard below).
const setTriggerRef = React.useCallback(
(node: HTMLAnchorElement | null) => {
triggerRef.current = node;
if (typeof ref === "function") ref(node);
else if (ref) ref.current = node;
},
[ref],
);
const cancelScheduledOpen = React.useCallback(() => {
if (openTimerRef.current) {
clearTimeout(openTimerRef.current);
openTimerRef.current = null;
}
}, []);
// Open immediately (keyboard focus, or re-entering the open popover).
const openNow = React.useCallback(() => {
cancelScheduledOpen();
openQuicklookId(instanceId);
}, [cancelScheduledOpen, instanceId]);
// Open after the hover-intent delay (pointer entering a card).
const scheduleOpen = React.useCallback(() => {
cancelScheduledOpen();
openTimerRef.current = setTimeout(() => {
openTimerRef.current = null;
openQuicklookId(instanceId);
}, QUICKLOOK_OPEN_DELAY_MS);
}, [cancelScheduledOpen, instanceId]);
const close = React.useCallback(() => {
cancelScheduledOpen();
closeQuicklookId(instanceId);
}, [cancelScheduledOpen, instanceId]);
// Clear any pending timer and release the active slot on unmount.
React.useEffect(() => {
return () => {
cancelScheduledOpen();
closeQuicklookId(instanceId);
};
}, [cancelScheduledOpen, instanceId]);
// Pointer-escape guard.
//
// The only close paths are `mouseleave` on the trigger and on the content,
// and a leave event is not guaranteed: when the layout shifts, the element
// moves out from under a stationary pointer rather than the pointer moving
// off the element, and no leave fires. Expanding a decision row does exactly
// that, stranding an open quicklook on screen until something else happens
// to open one.
//
// Rather than enumerate the ways a leave can be missed, re-check the
// browser's own hover state on every pointer move and close as soon as the
// pointer is over neither the trigger nor the card. Keyboard use is exempt:
// a quicklook opened by focus stays put while focus remains inside it.
React.useEffect(() => {
if (!open) return;
// Slack around each box, so crossing the 4px gap between the trigger and
// the card does not read as leaving.
const EDGE_SLACK_PX = 12;
const nearBox = (element: Element | null, x: number, y: number) => {
if (!element) return false;
const rect = element.getBoundingClientRect();
return (
x >= rect.left - EDGE_SLACK_PX
&& x <= rect.right + EDGE_SLACK_PX
&& y >= rect.top - EDGE_SLACK_PX
&& y <= rect.bottom + EDGE_SLACK_PX
);
};
const stillEngaged = (x: number, y: number) => {
const trigger = triggerRef.current;
const content = contentRef.current;
// Two independent signals, and closing needs both to agree the pointer is
// gone: `:hover` is authoritative about stacking and overlap, geometry
// survives the cases where hover state is not updated. Either one holding
// keeps the card open, so a real pointer resting on it is never dropped.
if (trigger?.matches(":hover") || content?.matches(":hover")) return true;
if (nearBox(trigger, x, y) || nearBox(content, x, y)) return true;
// Opened by keyboard: hold while focus is still inside.
const active = document.activeElement;
return trigger === active || (!!content && !!active && content.contains(active));
};
const onPointerMove = (event: PointerEvent) => {
if (!stillEngaged(event.clientX, event.clientY)) close();
};
document.addEventListener("pointermove", onPointerMove, { passive: true });
return () => document.removeEventListener("pointermove", onPointerMove);
}, [open, close]);
const prefetchedState = issuePrefetch ? withIssueDetailHeaderSeed(state, issuePrefetch) : state;
const { data, isLoading } = useQuery({
...getIssueDetailQueryOptions(queryClient, issuePathId, { placeholderIssue: issuePrefetch ?? undefined }),
enabled: open,
staleTime: ISSUE_DETAIL_STALE_TIME_MS,
});
const detailPath = createIssueDetailPath(issuePathId);
const prefetchHandlers = useIssueNavigationPrefetch(issuePathId, issuePrefetch);
const link = (
<RouterDom.Link
ref={setTriggerRef}
to={to}
state={prefetchedState}
className={className}
onMouseEnter={(event) => {
prefetchHandlers.onMouseEnter(event);
onMouseEnter?.(event);
}}
onMouseLeave={(event) => {
prefetchHandlers.onMouseLeave(event);
onMouseLeave?.(event);
}}
onPointerDown={(event) => {
prefetchHandlers.onPointerDown(event);
onPointerDown?.(event);
}}
onFocus={(event) => {
prefetchHandlers.onFocus(event);
openNow();
onFocus?.(event);
}}
onBlur={(event) => {
prefetchHandlers.onBlur(event);
// Let clicks inside the portaled quicklook content finish before closing.
setTimeout(() => close(), 0);
onBlur?.(event);
}}
onTouchStart={(event) => {
prefetchHandlers.onTouchStart(event);
onTouchStart?.(event);
}}
onClickCapture={(event) => {
prefetchHandlers.onClickCapture(event);
onClickCapture?.(event);
}}
onClick={(event) => {
close();
onClick?.(event);
}}
{...props}
>
{children}
</RouterDom.Link>
);
if (disableIssueQuicklook) {
return link;
}
return (
<Popover open={open} onOpenChange={(next) => (next ? openNow() : close())}>
<PopoverTrigger
asChild
// The link's own hover handler warms the task; history waits for a dwell.
onMouseEnter={scheduleOpen}
onMouseLeave={close}
>
{link}
</PopoverTrigger>
<PopoverContent
ref={contentRef}
// Opts into the scale-from-trigger motion defined in index.css.
data-quicklook
className={QUICKLOOK_CONTENT_CLASS}
side={issueQuicklookSide}
align={issueQuicklookAlign}
alignOffset={quicklookAlignOffset(issueQuicklookAlign)}
onMouseEnter={openNow}
onMouseLeave={close}
// A preview must not move focus in either direction. Opening already
// declined to take focus; closing has to decline to hand it back, or
// Radix focuses the trigger on the way out — and because this link
// opens the quicklook `onFocus`, that focus immediately reopens the
// card that was just dismissed. Hovering away then leaves it up
// permanently: close, refocus, reopen, forever.
onOpenAutoFocus={(event) => event.preventDefault()}
onCloseAutoFocus={(event) => event.preventDefault()}
>
{data ? (
<IssueQuicklookCard issue={data} linkTo={detailPath} linkState={prefetchedState} compact />
) : (
<div className="space-y-2">
<div className="h-4 w-24 rounded bg-accent/50" />
<div className="h-4 w-full rounded bg-accent/40" />
<div className="h-4 w-3/4 rounded bg-accent/30" />
{!isLoading ? (
<p className="text-xs text-muted-foreground">Unable to load task preview.</p>
) : null}
</div>
)}
</PopoverContent>
</Popover>
);
});