plugins/karakeep
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

bookmarks as cards, with the picture the page carries

Browse Source 
A list of titles and addresses is what a browser's own bookmark bar does. The
reason to keep pages here is that they have been fetched and archived, and a
grid of covers is the cheapest way to show that.

── Which picture, and the trade it costs ──

A crawled bookmark carries two: `content.imageUrl`, the page's own og:image, and
a `screenshot` asset Karakeep took and stores itself. The screenshot is better -
archived, cannot rot, never leaves the house - and it is unreachable from an
`<img>`: Officer authenticates with a bearer token in a header and a browser
cannot put a header on an image request, so the asset route answers 401 from
markup. Fetching each as a blob would work and costs a request, a decode and an
object URL per card.

So the origin's image, with referrerPolicy="no-referrer" so those sites learn
nothing about where the request came from, and loading="lazy" so a long grid does
not fetch a hundred at once. The honest cost, written at the point of use:
viewing your bookmarks makes requests to the sites they point at. Proxying the
archived asset is the fix if that ever matters.

── The empty state is three states ──

Not crawled yet, crawled with nothing to find, and a picture that failed to load.
The first is temporary and the others are not, so it says "fetching…" and the
header counts how many are still going. Measured on the live instance while
writing this: 6 of 50 crawled, the rest pending - so a fresh import spends a
while looking like a broken panel unless it explains itself.

Grid is auto-fill on a minimum width rather than a column count, because this is
one pane of a layout the owner can drag and the columns have to follow the width
it is actually given.
This commit is contained in:
pastilhas
2026-09-05 21:42:28 +01:00
parent bf6d9f5cb3
commit da94c6d7ff
2 changed files with 151 additions and 53 deletions
Download Patch File Download Diff File Expand all files Collapse all files
manifest.ts
+1 -1
View File
@@ -40,7 +40,7 @@ import type { PluginManifest } from '@@/plugins/manifest';
*/ */
export const manifest: PluginManifest = { export const manifest: PluginManifest = {
publisher: 'officerdev', publisher: 'officerdev',
version: '2026.09.05.01', version: '2026.09.05.02',
platform: '>=1.0.0', platform: '>=1.0.0',
label: 'Karakeep', label: 'Karakeep',
web/BookmarksPanel.tsx
+148 -50
View File
@@ -2,7 +2,7 @@ import { useCallback, useEffect, useRef, useState } from 'react';
import { useSearchParams } from 'react-router'; import { useSearchParams } from 'react-router';
import { useClient } from 'hooks/useClient'; import { useClient } from 'hooks/useClient';
import { Input } from '@/components/ui/input'; import { Input } from '@/components/ui/input';
import { ExternalLink, FileText, StickyNote, Image as ImageIcon } from 'lucide-react'; import { StickyNote, Image as ImageIcon, Link2 } from 'lucide-react';
import { ALL } from './ListsPanel'; import { ALL } from './ListsPanel';
/** /**
@@ -15,28 +15,33 @@ import { ALL } from './ListsPanel';
* ── Search is Karakeep's, not ours ── * ── Search is Karakeep's, not ours ──
* *
* `/bookmarks/search?q=` searches titles, notes, tags and the archived text. Re-implementing it here * `/bookmarks/search?q=` searches titles, notes, tags and the archived text. Re-implementing it here
* would mean pulling every bookmark to the browser to filter it, and would still only see the fields we * would mean pulling every bookmark to the browser to filter, and would still only see the fields we
* happened to fetch. * happened to fetch.
*/ */
/** type Asset = { id: string; assetType?: string; fileName?: string | null };
* A bookmark is a discriminated union on `content.type` — a link, a note, or an asset.
*
* Officer reads the minimum: enough to draw a row and open the thing. Everything else stays Karakeep's,
* which is what keeps an upstream field addition from being a change here.
*/
type Bookmark = { type Bookmark = {
id: string; id: string;
title?: string | null; title?: string | null;
createdAt?: string; createdAt?: string;
tags?: { id: string; name: string }[]; tags?: { id: string; name: string }[];
assets?: Asset[];
content?: content?:
| { type: 'link'; url: string; title?: string | null; description?: string | null } | {
type: 'link';
url: string;
title?: string | null;
description?: string | null;
imageUrl?: string | null;
favicon?: string | null;
publisher?: string | null;
crawlStatus?: string | null;
}
| { type: 'text'; text?: string } | { type: 'text'; text?: string }
| { type: 'asset'; assetType?: string; fileName?: string | null }; | { type: 'asset'; assetType?: string; fileName?: string | null };
}; };
/** Paginated, and the cursor is ignored for now — the first page is a screenful. */
type Page = { bookmarks?: Bookmark[]; nextCursor?: string | null }; type Page = { bookmarks?: Bookmark[]; nextCursor?: string | null };
export const BookmarksPanel = () => { export const BookmarksPanel = () => {
@@ -54,10 +59,10 @@ export const BookmarksPanel = () => {
const load = useCallback(async (listId: string, search: string) => { const load = useCallback(async (listId: string, search: string) => {
/* /*
Three different endpoints, because Karakeep models them as three questions rather than one with Three endpoints, because Karakeep models them as three questions rather than one with filters:
filters: everything, one list's contents, and a search. Search wins when there is one — narrowing a everything, one list's contents, and a search. Search wins when there is one — narrowing a search
search to a list is a fourth thing the API does not offer, and pretending otherwise here would mean to a list is a fourth thing the API does not offer, and faking it by filtering here would be a
filtering results in the browser and calling it the same feature. different feature wearing the same label.
*/ */
const path = const path =
search.trim() ? `/karakeep/api/v1/bookmarks/search?q=${encodeURIComponent(search.trim())}` search.trim() ? `/karakeep/api/v1/bookmarks/search?q=${encodeURIComponent(search.trim())}`
@@ -74,13 +79,15 @@ export const BookmarksPanel = () => {
} }
}, []); }, []);
// Debounced, because this types straight into a request: long enough that a five-letter word is one // Debounced: long enough that a five-letter word is one query instead of five, short enough that the
// query instead of five, short enough that the list moves while you type. // grid moves while you type.
useEffect(() => { useEffect(() => {
const timer = setTimeout(() => void load(list, query), 250); const timer = setTimeout(() => void load(list, query), 250);
return () => clearTimeout(timer); return () => clearTimeout(timer);
}, [list, query, load]); }, [list, query, load]);
const waiting = rows?.filter((b) => b.content?.type === 'link' && b.content.crawlStatus === 'pending').length ?? 0;
return ( return (
<div className="flex size-full flex-col"> <div className="flex size-full flex-col">
<header className="border-b p-2"> <header className="border-b p-2">
@@ -90,10 +97,16 @@ export const BookmarksPanel = () => {
placeholder="Search titles, notes, tags and saved text…" placeholder="Search titles, notes, tags and saved text…"
className="h-8 text-xs" className="h-8 text-xs"
/> />
{query.trim() && list !== ALL && ( <div className="mt-1 flex flex-wrap gap-x-3 text-[10px] text-muted-foreground">
// Said rather than silently ignored: the result set is not what the sidebar implies. {query.trim() && list !== ALL && <span>Searching everything, not just this list.</span>}
<p className="mt-1 text-[10px] text-muted-foreground">Searching everything, not just this list.</p> {/*
)} Said, rather than left as a grid of blank tiles.
A bookmark has no picture until Karakeep has crawled it, and on a fresh import that is most
of them for a while. Without this the panel looks broken at exactly the moment it is working.
*/}
{waiting > 0 && <span>{waiting} still being fetched — pictures appear as they finish.</span>}
</div>
</header> </header>
{error && ( {error && (
@@ -108,54 +121,66 @@ export const BookmarksPanel = () => {
) : rows && rows.length === 0 ? ( ) : rows && rows.length === 0 ? (
<Centred>{query.trim() ? `Nothing matches “${query.trim()}”.` : 'Nothing saved here yet.'}</Centred> <Centred>{query.trim() ? `Nothing matches “${query.trim()}”.` : 'Nothing saved here yet.'}</Centred>
) : ( ) : (
<ul className="flex-1 divide-y overflow-auto"> <div className="flex-1 overflow-auto p-3">
{/*
`auto-fill` with a minimum, not a fixed column count: the panel is one pane of a layout the
owner can drag, so the number of columns has to follow the width it is actually given rather
than a breakpoint guessed from the window.
*/}
<div className="grid grid-cols-[repeat(auto-fill,minmax(210px,1fr))] gap-3">
{rows?.map((bookmark) => ( {rows?.map((bookmark) => (
<li key={bookmark.id} className="group px-3 py-2 hover:bg-muted/40"> <Card key={bookmark.id} bookmark={bookmark} />
<Row bookmark={bookmark} />
</li>
))} ))}
</ul> </div>
</div>
)} )}
</div> </div>
); );
}; };
const Row = ({ bookmark }: { bookmark: Bookmark }) => { const Card = ({ bookmark }: { bookmark: Bookmark }) => {
const content = bookmark.content; const content = bookmark.content;
const url = content?.type === 'link' ? content.url : null; const link = content?.type === 'link' ? content : null;
const url = link?.url ?? null;
const title = const title =
bookmark.title || bookmark.title ||
(content?.type === 'link' ? content.title : null) || link?.title ||
(content?.type === 'asset' ? content.fileName : null) || (content?.type === 'asset' ? content.fileName : null) ||
(content?.type === 'text' ? content.text?.slice(0, 80) : null) || (content?.type === 'text' ? content.text?.slice(0, 120) : null) ||
url || url ||
'Untitled'; 'Untitled';
const Icon = content?.type === 'text' ? StickyNote : content?.type === 'asset' ? ImageIcon : FileText; const host = (() => {
if (!url) return null;
try {
return new URL(url).hostname.replace(/^www\./, '');
} catch {
// A saved address that does not parse is still a bookmark; it just has no domain to show.
return null;
}
})();
return ( const Body = (
<div className="flex items-start gap-2"> <>
<Icon className="mt-0.5 size-3.5 shrink-0 text-muted-foreground" /> <Picture bookmark={bookmark} title={title} />
<div className="min-w-0 flex-1">
{url ? ( <div className="flex min-w-0 flex-1 flex-col gap-1 p-2">
<a <p className="line-clamp-2 text-xs leading-snug">{title}</p>
href={url}
target="_blank" {host && (
rel="noreferrer noopener" <p className="flex items-center gap-1 truncate text-[10px] text-muted-foreground">
className="flex items-center gap-1 text-xs hover:underline" {link?.favicon && (
> // Decorative: the domain beside it already says what this is.
<span className="min-w-0 truncate">{title}</span> <img src={link.favicon} alt="" loading="lazy" referrerPolicy="no-referrer" className="size-3 shrink-0 rounded-sm" />
<ExternalLink className="size-3 shrink-0 opacity-0 transition-opacity group-hover:opacity-60" /> )}
</a> <span className="truncate">{host}</span>
) : ( </p>
// A note or an asset has nowhere to go, so it is not dressed as a link.
<span className="block truncate text-xs">{title}</span>
)} )}
{url && <p className="truncate text-[11px] text-muted-foreground">{url}</p>}
{bookmark.tags && bookmark.tags.length > 0 && ( {bookmark.tags && bookmark.tags.length > 0 && (
<p className="mt-0.5 flex flex-wrap items-center gap-1 text-[10px] text-muted-foreground"> <p className="mt-auto flex flex-wrap gap-1 pt-1 text-[10px] text-muted-foreground">
{bookmark.tags.map((tag) => ( {bookmark.tags.slice(0, 3).map((tag) => (
<span key={tag.id} className="rounded bg-muted px-1 py-px"> <span key={tag.id} className="rounded bg-muted px-1 py-px">
{tag.name} {tag.name}
</span> </span>
@@ -163,6 +188,79 @@ const Row = ({ bookmark }: { bookmark: Bookmark }) => {
</p> </p>
)} )}
</div> </div>
</>
);
const shell = 'flex flex-col overflow-hidden rounded-md border border-border bg-card transition-colors hover:border-foreground/25';
// A note or an asset has nowhere to go, so it is not dressed as something clickable.
return url ? (
<a href={url} target="_blank" rel="noreferrer noopener" className={shell}>
{Body}
</a>
) : (
<div className={shell}>{Body}</div>
);
};
/**
* The card's picture, or an honest stand-in.
*
* ── Why the ORIGIN's image and not Karakeep's screenshot ──
*
* A crawled bookmark carries both: `content.imageUrl`, the page's own og:image, and a `screenshot`
* asset that Karakeep took and stores itself. The screenshot is the better picture — it is archived, it
* cannot rot, and it never leaves the house.
*
* It is also unreachable from an `<img>`. Officer authenticates with a bearer token in a header, and a
* browser cannot put a header on an image request, so `/api/karakeep/api/assets/<id>` answers 401 from
* markup. Fetching each one as a blob through the client would work and costs a request, a decode and an
* object URL per card, which is a lot of machinery for a thumbnail.
*
* So this uses the origin's image, with `referrerPolicy="no-referrer"` so the sites being fetched from
* learn nothing about where the request came from, and `loading="lazy"` so a long grid does not fetch a
* hundred of them at once. The honest cost: viewing your bookmarks makes requests to the sites they
* point at. Proxying the archived asset instead is the fix if that matters — see the note above for what
* it would take.
*/
const Picture = ({ bookmark, title }: { bookmark: Bookmark; title: string }) => {
const [broken, setBroken] = useState(false);
const content = bookmark.content;
const image = content?.type === 'link' ? content.imageUrl : null;
const pending = content?.type === 'link' && content.crawlStatus === 'pending';
if (image && !broken) {
return (
<div className="aspect-video w-full overflow-hidden bg-muted">
<img
src={image}
alt=""
loading="lazy"
referrerPolicy="no-referrer"
onError={() => setBroken(true)}
className="size-full object-cover"
/>
</div>
);
}
/*
The stand-in, which is deliberately not a grey rectangle.
Three states land here and they are not the same: not crawled yet, crawled with no picture to find,
and a picture that failed to load. The first is temporary and the others are permanent, so the first
says so — otherwise a fresh import reads as a broken panel for as long as the crawler takes.
*/
const Icon = content?.type === 'text' ? StickyNote : content?.type === 'asset' ? ImageIcon : Link2;
return (
<div className="flex aspect-video w-full flex-col items-center justify-center gap-1 bg-muted/40 px-2">
<Icon className="size-5 text-muted-foreground/50" />
{pending ? (
<span className="text-[10px] text-muted-foreground/70">fetching…</span>
) : (
<span className="line-clamp-2 text-center text-[10px] text-muted-foreground/60">{title}</span>
)}
</div> </div>
); );
}; };