Add link preview cards (og:image, favicon, title, description)

URLs pasted into notes are scraped server-side with open-graph-scraper
and displayed as unfurl cards at the bottom of each NoteCard. Previews
populate automatically after save via a background fetch and socket push.
Cards cap at 3; collapse to 1 when the note already has images/sketches.
Border uses --border-transparent so cards look natural on all note colors.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: alexmicuplusfour

client/src/components/LinkPreviewCard.jsx

@@ -0,0 +1,133 @@
+import React from 'react';
+import styled from 'styled-components';
+import { getServerUrl } from '../services/api';
+import { useUIPreferences } from '../contexts/UIPreferencesContext';
+
+const Card = styled.a`
+  /* Flex column so the image can shrink when the note card is tight on space,
+     letting several previews compress to fit instead of overflowing. */
+  display: flex;
+  flex-direction: column;
+  flex: 0 1 auto;
+  min-height: 52px;
+  text-decoration: none;
+  color: inherit;
+  border: 1px solid var(--border-transparent);
+  border-radius: 8px;
+  overflow: hidden;
+  cursor: pointer;
+  transition: opacity 0.15s ease;
+
+  &:hover {
+    opacity: 0.8;
+  }
+`;
+
+const CardImage = styled.div`
+  width: 100%;
+  /* Basis of 130px but allowed to shrink to 0 (never grows), so the image is the
+     part that gives when previews need to fit a bounded area. */
+  flex: 0 1 130px;
+  min-height: 0;
+  background-image: url(${props => props.$src});
+  background-size: cover;
+  background-position: center;
+  background-color: ${props => props.theme === 'dark' ? 'rgba(255,255,255,0.05)' : 'rgba(0,0,0,0.04)'};
+`;
+
+const CardBody = styled.div`
+  padding: 7px 10px 8px;
+  flex-shrink: 0; /* keep the text (favicon/domain/title) legible; only the image shrinks */
+`;
+
+const CardMeta = styled.div`
+  display: flex;
+  align-items: center;
+  gap: 5px;
+  margin-bottom: 3px;
+`;
+
+const Favicon = styled.img`
+  width: 13px;
+  height: 13px;
+  object-fit: contain;
+  flex-shrink: 0;
+`;
+
+const Domain = styled.span`
+  font-size: 11px;
+  color: ${props => props.theme === 'dark' ? 'rgba(255,255,255,0.45)' : 'rgba(0,0,0,0.45)'};
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+`;
+
+const CardTitle = styled.div`
+  font-size: 13px;
+  font-weight: 600;
+  line-height: 1.35;
+  display: -webkit-box;
+  -webkit-line-clamp: ${props => props.$oneLine ? 1 : 2};
+  -webkit-box-orient: vertical;
+  overflow: hidden;
+  color: var(--text-color);
+`;
+
+const CardDesc = styled.div`
+  font-size: 12px;
+  color: ${props => props.theme === 'dark' ? 'rgba(255,255,255,0.5)' : 'rgba(0,0,0,0.5)'};
+  margin-top: 2px;
+  line-height: 1.4;
+  display: -webkit-box;
+  -webkit-line-clamp: ${props => props.$oneLine ? 1 : 2};
+  -webkit-box-orient: vertical;
+  overflow: hidden;
+`;
+
+function LinkPreviewCard({ link, isDark, showImage = true, oneLine = false }) {
+  const { showLinkPreviews, showLinkPreviewImages } = useUIPreferences();
+  const theme = isDark ? 'dark' : 'light';
+
+  // Previews disabled entirely — render nothing (the data is still fetched/stored
+  // server-side, so re-enabling shows them instantly without a refetch).
+  if (!showLinkPreviews) return null;
+
+  let domain = '';
+  try {
+    domain = new URL(link.url).hostname.replace(/^www\./, '');
+  } catch {
+    domain = link.url;
+  }
+
+  // Image shown only when the setting is on AND the caller allows it (hidden once
+  // there are 3 cards, to keep them compact).
+  const imageUrl = (showImage && showLinkPreviewImages) ? getServerUrl(link.image_url) : null;
+  const faviconUrl = getServerUrl(link.favicon_url);
+
+  return (
+    <Card
+      href={link.url}
+      target="_blank"
+      rel="noopener noreferrer"
+      onClick={e => e.stopPropagation()}
+    >
+      {imageUrl && <CardImage $src={imageUrl} theme={theme} />}
+      <CardBody>
+        <CardMeta>
+          {faviconUrl && (
+            <Favicon
+              src={faviconUrl}
+              alt=""
+              onError={e => { e.target.style.display = 'none'; }}
+            />
+          )}
+          <Domain theme={theme}>{domain}</Domain>
+        </CardMeta>
+        {link.title && <CardTitle $oneLine={oneLine}>{link.title}</CardTitle>}
+        {link.description && <CardDesc theme={theme} $oneLine={oneLine}>{link.description}</CardDesc>}
+      </CardBody>
+    </Card>
+  );
+}
+
+export default LinkPreviewCard;

client/src/components/NoteCard.jsx

@@ -2,7 +2,7 @@ import React, { useState, useEffect, memo, useCallback, useRef, useMemo, useSync
 import styled, { keyframes, css } from 'styled-components';
 import { useNoteActions } from '../contexts/NoteActionsContext'; // Use stable actions context
 import { selectionModeRef } from '../contexts/NoteSelectionContext';
-import { tagsApi, getServerUrl } from '../services/api';
+import { tagsApi } from '../services/api';
 import NoteTagPicker, { TagPicker } from './NoteTagPicker';
 import { ColorPicker as SharedColorPicker } from './ColorPicker'; // Import the new ColorPicker
 import Icon from './Icons';
@@ -11,6 +11,7 @@ import ImageGallery from './ImageGallery';
 import ProgressFlyout from './ProgressFlyout';
 import CompactBookCard from './CompactBookCard';
 import CompactImdbCard from './CompactImdbCard';
+import LinkPreviewCard from './LinkPreviewCard';
 import { loadNoteImages } from '../services/imageManager';
 import { useInlineImageResolution } from '../hooks/useInlineImageResolution';
 
@@ -93,7 +94,7 @@ const Card = styled.div`
   padding: 16px;
   padding-bottom: 8px;
   height: fit-content; /* Key for masonry layout: use fit-content instead of min-height */
-  max-height: ${props => props.$hasImages ? '620px' : '460px'};
+  max-height: ${props => props.$hasImages ? '620px' : props.$hasLinks ? '600px' : '460px'};
   display: flex;
   flex-direction: column;
   transition: box-shadow 0.2s ease, transform 0.2s ease, opacity 0.3s ease;
@@ -121,7 +122,7 @@ const Card = styled.div`
   @media (max-width: 600px) {
       padding: 12px;
       font-size: 0.9em;
-      max-height: ${props => props.$hasImages ? '440px' : props.$hasTags ? '380px' :  '250px'};
+      max-height: ${props => props.$hasImages ? '440px' : props.$hasLinks ? '440px' : props.$hasTags ? '380px' :  '250px'};
       /* Use CSS variable for mobile background */
       background-color: var(--card-bg-color, var(--mobile-background-color));
       border: ${props => props.$isDirectIdMatch
@@ -526,6 +527,30 @@ const TagText = styled.span`
   min-width: 0;
 `;
 
+// Holds the stack of link preview cards. A flex column with a bounded height: when
+// several (image-heavy) previews would overflow, the cards themselves shrink to fit
+// (their images compress) rather than the card spilling or the note text getting
+// starved. flex-shrink:999 + min-height:0 makes THIS section yield first under
+// pressure. Collapses to no margin when it renders empty (previews toggled off).
+const LinkPreviewList = styled.div`
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  min-height: 0;
+  flex-shrink: 999;
+  max-height: 300px;
+  margin: 8px 0 10px;
+
+  &:empty {
+    margin: 0;
+  }
+
+  /* When the note already has images/sketches, only the first preview is shown */
+  ${props => props.$compact && `
+    > *:nth-child(n+2) { display: none; }
+  `}
+`;
+
 const UrlLink = styled(Tag)`
 
 `;
@@ -670,7 +695,6 @@ const extractNoteReferences = (text, urlsToExclude = []) => {
 };
 
 const NoteCard = memo(function NoteCard({ note, searchQuery, layoutView, onPickerOpen, isSelected, onToggleSelect }) {
-  console.log('[NoteCard] Rendering note:', note.id);
   const [justEdited, setJustEdited] = useState(false);
   const [showActions, setShowActions] = useState(false);
   const [showColorPicker, setShowColorPicker] = useState(false);
@@ -1040,6 +1064,17 @@ const NoteCard = memo(function NoteCard({ note, searchQuery, layoutView, onPicke
     return noteTags.some(tag => tag.visible === false);
   }, [noteTags]);
 
+  // Renderable link previews (have a fetched title/image), capped at 3.
+  const previewLinks = useMemo(
+    () => (note.links || []).filter(l => l.title || l.image_url).slice(0, 3),
+    [note.links]
+  );
+  const hasLinkPreviews = previewLinks.length > 0;
+  // Images get cramped once there are three cards, so only show them for 1-2.
+  const showLinkImages = previewLinks.length <= 2;
+  // With more than one card, clamp each title/description to a single line.
+  const oneLinePreviewText = previewLinks.length > 1;
+
   // Compute inline style for color CSS variables - avoids styled-components class regeneration
   const cardColorStyle = useMemo(() => {
     const color = note.color || 'default';
@@ -1060,6 +1095,7 @@ const NoteCard = memo(function NoteCard({ note, searchQuery, layoutView, onPicke
         style={cardColorStyle}
         $isPinned={note.is_pinned}
         $hasImages={images.length > 0}
+        $hasLinks={hasLinkPreviews}
         $hasTags={visibleTags.length > 0} // Use visibleTags for layout check
         $justEdited={justEdited}
         $isSelected={isSelected}
@@ -1113,6 +1149,15 @@ const NoteCard = memo(function NoteCard({ note, searchQuery, layoutView, onPicke
           </div>
         )}
 
+        {/* Link preview cards (max 3; images hidden once there are 3) */}
+        {hasLinkPreviews && (
+          <LinkPreviewList $compact={images.length > 0 || sketches.length > 0}>
+            {previewLinks.map(link => (
+              <LinkPreviewCard key={link.id} link={link} isDark={isDarkTheme} showImage={showLinkImages} oneLine={oneLinePreviewText} />
+            ))}
+          </LinkPreviewList>
+        )}
+
         {/* Display tags, URLs, book references, note references, and objects if any */}
         {(noteTags.length > 0 || noteUrls.length > 0 || bookReferences.length > 0 || noteReferences.length > 0 || noteObjects.length > 0) && (
           <TagsContainer style={{
@@ -1443,6 +1488,18 @@ const NoteCard = memo(function NoteCard({ note, searchQuery, layoutView, onPicke
     }
   }
 
+  // Check for link preview updates. Preview fetches (title/image/favicon) update
+  // the note_links table WITHOUT bumping note.updated_at, so this must be compared
+  // explicitly — otherwise a card whose preview just arrived over the socket won't
+  // re-render until a full refresh.
+  const prevLinks = prevProps.note.links || [];
+  const nextLinks = nextProps.note.links || [];
+  if (prevLinks.length !== nextLinks.length) return false;
+  for (let i = 0; i < prevLinks.length; i++) {
+    if (prevLinks[i].id !== nextLinks[i].id) return false;
+    if (prevLinks[i].fetched_at !== nextLinks[i].fetched_at) return false;
+  }
+
   // For large content, only check length to avoid expensive comparison
   const prevContent = prevProps.note.content || '';
   const nextContent = nextProps.note.content || '';

client/src/components/settings/AppearanceTab.jsx

@@ -85,11 +85,15 @@ const AppearanceTab = ({ settings, commit, isDarkTheme, toggleTheme }) => {
     showQuickAccess,
     showMonthMarkers,
     showNoteTabs,
+    showLinkPreviews,
+    showLinkPreviewImages,
     fullscreenNoteForm,
     layoutView,
     toggleQuickAccess,
     toggleMonthMarkers,
     toggleNoteTabs,
+    toggleLinkPreviews,
+    toggleLinkPreviewImages,
     toggleFullscreenNoteForm,
     changeLayoutView,
     colorLabels,
@@ -317,6 +321,31 @@ const AppearanceTab = ({ settings, commit, isDarkTheme, toggleTheme }) => {
         </p>
       </SectionContainer>
 
+      <SectionContainer>
+        <SectionTitle>Link Previews</SectionTitle>
+        <OptionRow>
+          <Label style={{ marginBottom: 0 }}>Show Link Previews</Label>
+          <Switch
+            id="link-previews-toggle"
+            checked={showLinkPreviews}
+            onChange={toggleLinkPreviews}
+          />
+        </OptionRow>
+        {showLinkPreviews && (
+          <OptionRow>
+            <Label style={{ marginBottom: 0 }}>Show Preview Images</Label>
+            <Switch
+              id="link-preview-images-toggle"
+              checked={showLinkPreviewImages}
+              onChange={toggleLinkPreviewImages}
+            />
+          </OptionRow>
+        )}
+        <p style={{ fontSize: '14px', color: 'var(--text-secondary-color)', margin: 0 }}>
+          Preview cards for links that sit alone on their own line.
+        </p>
+      </SectionContainer>
+
       <SectionContainer>
         <SectionTitle>Custom Color Labels</SectionTitle>
         <p style={{ fontSize: '14px', color: 'var(--text-secondary-color)' }}>

client/src/contexts/NotesContext.jsx

@@ -51,6 +51,13 @@ const notesArrayEqual = (a, b) => {
     ) {
       return false;
     }
+    const xl = x.links, yl = y.links;
+    const xll = xl ? xl.length : 0;
+    const yll = yl ? yl.length : 0;
+    if (xll !== yll) return false;
+    for (let j = 0; j < xll; j++) {
+      if (xl[j].fetched_at !== yl[j].fetched_at) return false;
+    }
   }
   return true;
 };