Files
Marcos Paulo b32650767c
ci / ci (macos-latest) (push) Has been cancelled
ci / ci (ubuntu-latest) (push) Has been cancelled
ci / ci (windows-latest) (push) Has been cancelled
docs: specs and briefs for smart folders, version diff, media timestamps, clean paste, link cards, spaced repetition
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-21 12:18:00 -03:00

6.7 KiB

Rich link bookmark cards (OpenGraph), cached offline (agy gap 10, roadmap 30)

Part of specs/plugins-parity/. No new crate. Reuses the tokenizer of notescraft-htmlmd (clean-paste, task 1), ureq (already approved, engine uses it), sha2 (approved).

Research (2026-10-21; agy claims checked)

  • Notion bookmarks, Capacities weblinks (title, description, favicon, hero image), Craft link cards, Bear: from agy; Capacities is the only one linked (https://capacities.io/docs/objects/weblinks), not fetched here. Bear: not verified. Treat "who has it" as Notion, Capacities, Craft (unverified details).
  • Obsidian: community plugins Link Embed / Auto Card Link fill the gap (not verified in this run: search returned nothing; names from memory, check before citing). Obsidian itself renders bare URLs as plain links.
  • Standard: Open Graph protocol https://ogp.me/ (og:title, og:description, og:image, og:site_name, og:url), with fallbacks <title>, <meta name=description>, <link rel=icon>.
  • Privacy risk is the reason for the strict policy below: fetching a URL leaks the user's IP and the fact that a note links there. This conflicts with the roadmap "Network policy reminder" (no title fetching for pasted links without its own spec section and a settings switch): THIS spec is that section.

Problem

A note full of bare links is unreadable ("what was that URL?"). Cards show title, site and summary at a glance and still work offline.

Goal

A line that contains ONLY a URL (a standalone paragraph, https://..., no other text) renders as a bookmark card in live preview when metadata is cached; the Markdown stays the bare URL (portable). Fetching happens ONLY when the user asks: context menu "Fetch link card" on a URL, palette "Link card: Fetch for the URL under the cursor", or the paste toast action "Make card" after a URL paste. Never automatic.

Non-goals (v1)

Automatic fetching on paste or on note open; background refresh; thumbnails/hero images (Q1); oEmbed/YouTube players; crawling robots.txt; link cards inside tables or lists; writing the title into the note (Feature ideas 2).

Design decisions

D1 Network policy (hard rules)

  • Setting web.link_cards (bool, default false). Off: linkcard.fetch returns network_disabled; the UI shows the enable notice (same pattern as the Maps placeholder).
  • A fetch runs only from a command the user triggered. Not in ai/assistant_gate.rs at all (neither READ nor WRITE list) so an AI agent cannot trigger network.
  • URL guard (crates/engine/src/linkcard/url.rs, pure): scheme http/https only; no userinfo; length <= 2048; host not localhost, not an IP literal that is loopback/private/link-local/unspecified/multicast/CGNAT; max 3 redirects, each re-checked; timeout 8 s total; response body read up to 512 KiB (the <head> is all that is needed); Content-Type must be text/html or application/xhtml+xml; one request in flight per URL; global limit 4 concurrent. Ceiling (documented): DNS names resolving to private IPs (rebinding) are not blocked in v1; user-initiated so accepted, upgrade path: a custom ureq resolver. Q2.
  • User agent NotesCraft/<version> (link card); no cookies, no referrer.

D2 Cache

.notescraft/cache/web/<sha256-hex(normalised-url)>.json written with write_private: {"v":1,"url","final_url","title","description","site","favicon":null|"data"?, "fetched_ms"}; fields clipped (title 200, description 500, site 80 chars), control characters removed. Max 2 000 entries; oldest evicted on write. URL normalisation: lowercase scheme/host, drop fragment, keep query. linkcard.get NEVER touches the network.

D3 Engine (crates/engine/src/linkcard/{mod,url,fetch,og,cache,commands}.rs)

id params result network writes
linkcard.get {url} `{card null}` no
linkcard.fetch {url, refresh?} {card} YES cache
linkcard.clear {url?} (none = all) {removed} no cache
og.rs uses notescraft_htmlmd::tokens::tokenize on the first 512 KiB, reads `<meta property name content>and